@vellumai/assistant 0.12.2 → 0.12.3-staging.1

package/src/desktop/desktop-help.ts

@@ -0,0 +1,15 @@
+import type { ToolContext, ToolExecutionResult } from "../tools/types.js";
+import { desktopAutomationLease } from "./desktop-automation-lease.js";
+import { isVirtualDesktopEnabled } from "./virtual-desktop-feature.js";
+
+export async function prepareDesktopHelp(
+  context: ToolContext,
+): Promise<ToolExecutionResult | ((resume: boolean) => Promise<void>)> {
+  if (!isVirtualDesktopEnabled()) {
+    return {
+      content: "Virtual desktop help is unavailable on this assistant.",
+      isError: true,
+    };
+  }
+  return desktopAutomationLease.reserveForHuman(context);
+}

package/src/desktop/desktop-stream-bridge.test.ts

@@ -1,8 +1,10 @@
+import * as fs from "node:fs";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { afterAll, describe, expect, test } from "bun:test";
+import { afterAll, describe, expect, mock, spyOn, test } from "bun:test";
 
+import { setOverridesForTesting } from "../__tests__/feature-flag-test-helpers.js";
 import { newFakeDesktop, newViewer, settle } from "./__tests__/fake-desktop.js";
 import { DesktopDependencyInstaller } from "./desktop-dependencies.js";
 import {
@@ -13,6 +15,7 @@ import {
   getDesktopSessionManager,
 } from "./desktop-session-manager.js";
 import { DesktopStreamBridge } from "./desktop-stream-bridge.js";
+import { isVirtualDesktopEnabled } from "./virtual-desktop-feature.js";
 
 const profileDir = mkdtempSync(join(tmpdir(), "desktop-bridge-test-"));
 afterAll(() => {
@@ -87,6 +90,63 @@ function slotIsFree(manager: DesktopSessionManager): boolean {
 }
 
 describe("DesktopStreamBridge", () => {
+  test("streams without flag or filesystem checks after connecting", async () => {
+    const originalContainerized = process.env.IS_CONTAINERIZED;
+    const originalPlatform = process.env.IS_PLATFORM;
+    const h = newFakeDesktop({ profileDir });
+    const isEnabled = mock(isVirtualDesktopEnabled);
+    const b = newBridge(h.manager, async () => {}, isEnabled);
+    process.env.IS_CONTAINERIZED = "true";
+    process.env.IS_PLATFORM = "true";
+    setOverridesForTesting({ "assistant-desktop": true });
+    try {
+      b.connectNow();
+      await b.bridge.start();
+      expect(isEnabled).toHaveBeenCalled();
+      isEnabled.mockClear();
+      const stat = spyOn(fs, "statSync");
+      const read = spyOn(fs, "readFileSync");
+      try {
+        const frame = new Uint8Array([1, 2, 3]);
+        for (let i = 0; i < 100; i++) {
+          b.bridge.handleClientFrame(frame);
+          b.tcp.handlers.onData(frame);
+          b.tcp.handlers.onDrain();
+        }
+        expect(b.tcp.writes).toHaveLength(100);
+        expect(b.ws.sent).toHaveLength(100);
+        setOverridesForTesting({ "assistant-desktop": false });
+        b.bridge.handleClientFrame(frame);
+        b.tcp.handlers.onData(frame);
+        b.tcp.handlers.onDrain();
+        expect(b.tcp.writes).toHaveLength(101);
+        expect(b.ws.sent).toHaveLength(101);
+        expect(b.ws.closeCode).toBeNull();
+        expect(b.tcp.ended).toBe(false);
+        expect(isEnabled).not.toHaveBeenCalled();
+        expect(stat).not.toHaveBeenCalled();
+        expect(read).not.toHaveBeenCalled();
+      } finally {
+        stat.mockRestore();
+        read.mockRestore();
+      }
+    } finally {
+      b.bridge.handleClose();
+      await h.manager.destroy();
+      setOverridesForTesting({});
+      if (originalContainerized === undefined) {
+        delete process.env.IS_CONTAINERIZED;
+      } else {
+        process.env.IS_CONTAINERIZED = originalContainerized;
+      }
+      if (originalPlatform === undefined) {
+        delete process.env.IS_PLATFORM;
+      } else {
+        process.env.IS_PLATFORM = originalPlatform;
+      }
+    }
+  });
+
   test("refuses a disabled desktop before installation or process startup", async () => {
     const h = newFakeDesktop({ profileDir });
     let installs = 0;
@@ -124,24 +184,19 @@ describe("DesktopStreamBridge", () => {
   });
 
   for (const direction of ["viewer", "desktop"] as const) {
-    test(`blocks ${direction} frames when the flag is disabled after connection`, async () => {
+    test(`ignores ${direction} frames after the stream closes`, async () => {
       const h = newFakeDesktop({ profileDir });
-      let enabled = true;
-      const b = newBridge(
-        h.manager,
-        async () => {},
-        () => enabled,
-      );
+      const b = newBridge(h.manager);
       b.connectNow();
       await b.bridge.start();
-      enabled = false;
+      b.bridge.handleClose();
       const frame = new Uint8Array([1, 2, 3]);
       if (direction === "viewer") {
         b.bridge.handleClientFrame(frame);
       } else {
         b.tcp.handlers.onData(frame);
       }
-      expect(b.ws.closeCode).toBe(4008);
+      expect(b.ws.closeCode).toBeNull();
       expect(b.ws.sent).toHaveLength(0);
       expect(b.tcp.writes).toHaveLength(0);
       expect(b.tcp.ended).toBe(true);

package/src/desktop/desktop-stream-bridge.ts

@@ -102,7 +102,7 @@ export class DesktopStreamBridge {
     try {
       tcp = await this.connect(DESKTOP_VNC_PORT, {
         onData: (data) => {
-          if (!this.checkEnabled()) {
+          if (this.closed) {
             return;
           }
           if (this.ws.send(data) === 0) {
@@ -128,7 +128,7 @@ export class DesktopStreamBridge {
   }
 
   handleClientFrame(message: string | Uint8Array | ArrayBuffer): void {
-    if (!this.checkEnabled() || typeof message === "string") {
+    if (this.closed || typeof message === "string") {
       return;
     }
     const bytes =
@@ -148,7 +148,7 @@ export class DesktopStreamBridge {
   }
 
   private flush(): void {
-    if (!this.checkEnabled()) {
+    if (this.closed) {
       return;
     }
     const tcp = this.tcp;

package/src/desktop/desktop-wallpaper-renderer.ts

@@ -0,0 +1,132 @@
+import { readAvatarState } from "../avatar/avatar-manifest.js";
+import { readContainedAvatarRaster } from "../avatar/ensure-raster.js";
+import {
+  renderNotificationAvatarPng,
+  resolveNotificationAccentHex,
+} from "../avatar/notification-avatar.js";
+import { renderCharacterPng } from "../avatar/png-renderer.js";
+import { getResvg, isResvgAvailable } from "../avatar/resvg-lazy.js";
+import { isTemplatePlaceholder } from "../daemon/handlers/identity.js";
+import { getAssistantName } from "../daemon/identity-helpers.js";
+import { getLogger } from "../util/logger.js";
+import { getAvatarImagePath } from "../util/platform.js";
+import { escapeXmlContent } from "../util/xml.js";
+
+function wallpaperWordmark(
+  width: number,
+  height: number,
+  name: string | null,
+): string {
+  const normalized = name?.replace(/\s+/g, " ").trim();
+  const label =
+    normalized && !isTemplatePlaceholder(normalized) ? normalized : "Vellum";
+  const text = `<text id="wordmark" font-family="Liberation Sans, Arial, sans-serif" font-size="64" font-weight="700" letter-spacing="1.5">${escapeXmlContent(`${label} OS`)}</text>`;
+  const Resvg = getResvg();
+  const bounds = new Resvg(
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}">${text}</svg>`,
+  ).getBBox();
+  if (!bounds || bounds.width === 0) {
+    return "";
+  }
+  const depth = 6;
+  const scale = Math.min(
+    (height * 0.06) / 64,
+    (width * 0.72) / (bounds.width + depth),
+  );
+  const x = width / 2 - (bounds.x + (bounds.width + depth) / 2) * scale;
+  const layers = Array.from({ length: depth }, (_, index) => {
+    const offset = depth - index;
+    return `<use href="#wordmark" transform="translate(${offset} ${offset})" fill="#40535b"/>`;
+  }).join("");
+  return `<defs>
+    ${text}
+    <linearGradient id="letter-face" x2="0" y2="1">
+      <stop stop-color="#ffffff"/><stop offset=".48" stop-color="#e0e9e7"/>
+      <stop offset="1" stop-color="#9eb4ba"/>
+    </linearGradient>
+  </defs>
+  <g transform="translate(${x} ${height * 0.69}) scale(${scale})">
+    <use href="#wordmark" transform="translate(9 12)" fill="#080f14" opacity=".35"/>
+    ${layers}
+    <use href="#wordmark" fill="url(#letter-face)" stroke="#e8f1ed" stroke-opacity=".4" stroke-width=".5"/>
+  </g>`;
+}
+
+export function renderDesktopWallpaper(
+  width: number,
+  height: number,
+  avatar: Buffer | null,
+  accentHex: string | null,
+  assistantName: string | null = null,
+): Buffer {
+  const accent = /^#[\da-f]{6}$/i.test(accentHex ?? "")
+    ? accentHex!
+    : "#91a6b0";
+  const cx = width / 2;
+  const cy = height * 0.46;
+  const size = Math.min(width, height) * 0.24;
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}">
+    <defs>
+      <linearGradient id="base" x2="1" y2="1">
+        <stop stop-color="#202a30"/><stop offset="1" stop-color="#10171c"/>
+      </linearGradient>
+      <radialGradient id="glow">
+        <stop stop-color="${accent}" stop-opacity=".24"/>
+        <stop offset="1" stop-color="${accent}" stop-opacity="0"/>
+      </radialGradient>
+      <radialGradient id="shadow">
+        <stop stop-color="#000" stop-opacity=".25"/>
+        <stop offset="1" stop-color="#000" stop-opacity="0"/>
+      </radialGradient>
+    </defs>
+    <path fill="url(#base)" d="M0 0H${width}V${height}H0z"/>
+    <ellipse cx="${cx}" cy="${cy}" rx="${height * 0.7}" ry="${height * 0.6}" fill="url(#glow)"/>
+    <g fill="none" stroke="${accent}">
+      <circle cx="${cx}" cy="${cy}" r="${size * 0.76}" stroke-opacity=".16"/>
+      <circle cx="${cx}" cy="${cy}" r="${size * 1.25}" stroke-opacity=".09"/>
+      <circle cx="${cx}" cy="${cy}" r="${size * 1.9}" stroke-opacity=".05"/>
+    </g>
+    ${
+      avatar
+        ? `<ellipse cx="${cx}" cy="${cy + size * 0.48}" rx="${size * 0.7}" ry="${size * 0.16}" fill="url(#shadow)"/>
+    <image x="${cx - size / 2}" y="${cy - size / 2}" width="${size}" height="${size}" href="data:image/png;base64,${avatar.toString("base64")}"/>`
+        : ""
+    }
+    ${wallpaperWordmark(width, height, assistantName)}
+  </svg>`;
+  const Resvg = getResvg();
+  return Buffer.from(new Resvg(svg).render().asPng());
+}
+
+export async function renderCurrentDesktopWallpaper(
+  width: number,
+  height: number,
+): Promise<Buffer | null> {
+  if (!isResvgAvailable()) {
+    return null;
+  }
+  const state = readAvatarState();
+  const name = getAssistantName();
+  let raster = readContainedAvatarRaster(getAvatarImagePath());
+  if (!raster && state.kind === "character" && state.traits) {
+    try {
+      raster = renderCharacterPng(
+        state.traits.bodyShape,
+        state.traits.eyeStyle,
+        state.traits.color,
+      );
+    } catch (err) {
+      getLogger("desktop-wallpaper").warn(
+        { err },
+        "Could not render wallpaper avatar",
+      );
+    }
+  }
+  return renderDesktopWallpaper(
+    width,
+    height,
+    raster ? await renderNotificationAvatarPng(state, raster) : null,
+    resolveNotificationAccentHex(state),
+    name,
+  );
+}

package/src/desktop/desktop-wallpaper-worker.ts

@@ -0,0 +1,17 @@
+import { writeFile } from "node:fs/promises";
+
+import { renderCurrentDesktopWallpaper } from "./desktop-wallpaper-renderer.js";
+
+const [width, height, output] = process.argv.slice(2);
+if (
+  !output ||
+  !Number.isFinite(Number(width)) ||
+  !Number.isFinite(Number(height))
+) {
+  throw new Error("Wallpaper dimensions and output path are required");
+}
+const png = await renderCurrentDesktopWallpaper(Number(width), Number(height));
+if (png) {
+  await writeFile(output, png);
+}
+process.exit(0);

package/src/desktop/desktop-wallpaper.test.ts

@@ -1,18 +1,36 @@
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { afterEach, beforeEach, expect, test } from "bun:test";
+import {
+  afterEach,
+  beforeEach,
+  expect,
+  mock,
+  setDefaultTimeout,
+  test,
+} from "bun:test";
 
 import sharp from "sharp";
 
 import {
   __resetResvgCacheForTests,
   __setResvgCacheForTests,
+  getResvg,
 } from "../avatar/resvg-lazy.js";
-import {
-  renderCurrentDesktopWallpaper,
-  renderDesktopWallpaper,
-} from "./desktop-wallpaper.js";
+import { renderCurrentDesktopWallpaper } from "./desktop-wallpaper.js";
+import { renderDesktopWallpaper } from "./desktop-wallpaper-renderer.js";
+
+// Native resvg renders scan the system font database per instance, and on a
+// loaded CI runner the file's first render runs past bun's 5s default. Each
+// test file runs in its own process, so this doesn't leak.
+setDefaultTimeout(15_000);
 
 let workspace: string;
 let previousWorkspace: string | undefined;
@@ -70,7 +88,7 @@ test("renders the current uploaded avatar into an opaque desktop wallpaper", asy
   expect((await sharp(result).stats()).isOpaque).toBe(true);
 });
 
-test("regenerates a character from current traits when its raster is missing", async () => {
+test("renders a missing character raster without changing persisted avatar files", async () => {
   manifest({
     kind: "character",
     source: "pool",
@@ -78,9 +96,18 @@ test("regenerates a character from current traits when its raster is missing", a
     image: null,
     accent: null,
   });
+  const avatarDir = join(workspace, "data/avatar");
+  writeFileSync(join(avatarDir, "character-traits.json"), "preserve traits");
+  writeFileSync(join(avatarDir, "character-ascii.txt"), "preserve ASCII");
+  const snapshot = () =>
+    readdirSync(avatarDir)
+      .sort()
+      .map((file) => [file, readFileSync(join(avatarDir, file))]);
+  const before = snapshot();
   const result = (await renderCurrentDesktopWallpaper(480, 300))!;
   const empty = renderDesktopWallpaper(480, 300, null, null);
   expect(await centerPixel(result)).not.toEqual(await centerPixel(empty));
+  expect(snapshot()).toEqual(before);
 });
 
 test("missing and unreadable avatars produce the same neutral background", async () => {
@@ -189,3 +216,17 @@ test("names containing XML are rendered as text without injecting SVG shapes", a
   );
   expect((await wordmarkPixels(png)).length).toBeGreaterThan(0);
 });
+
+test("renders in a child without invoking the assistant's native rasterizer", async () => {
+  const render = mock(() => {
+    throw new Error("Rendering must not run on the assistant event loop");
+  });
+  __setResvgCacheForTests({
+    available: true,
+    Resvg: render as unknown as ReturnType<typeof getResvg>,
+  });
+  const png = await renderCurrentDesktopWallpaper(1600, 900);
+  expect(render).not.toHaveBeenCalled();
+  const metadata = await sharp(png!).metadata();
+  expect([metadata.width, metadata.height]).toEqual([1600, 900]);
+});

package/src/desktop/desktop-wallpaper.ts

@@ -1,98 +1,13 @@
-import { readAvatarState } from "../avatar/avatar-manifest.js";
-import {
-  renderNotificationAvatarPng,
-  resolveNotificationAccentHex,
-} from "../avatar/notification-avatar.js";
-import { getResvg, isResvgAvailable } from "../avatar/resvg-lazy.js";
-import { isTemplatePlaceholder } from "../daemon/handlers/identity.js";
-import { getAssistantName } from "../daemon/identity-helpers.js";
-import { escapeXmlContent } from "../util/xml.js";
+import { execFile } from "node:child_process";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
 
-function wallpaperWordmark(
-  width: number,
-  height: number,
-  name: string | null,
-): string {
-  const normalized = name?.replace(/\s+/g, " ").trim();
-  const label =
-    normalized && !isTemplatePlaceholder(normalized) ? normalized : "Vellum";
-  const text = `<text id="wordmark" font-family="Liberation Sans, Arial, sans-serif" font-size="64" font-weight="700" letter-spacing="1.5">${escapeXmlContent(`${label} OS`)}</text>`;
-  const Resvg = getResvg();
-  const bounds = new Resvg(
-    `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}">${text}</svg>`,
-  ).getBBox();
-  if (!bounds || bounds.width === 0) {
-    return "";
-  }
-  const depth = 6;
-  const scale = Math.min(
-    (height * 0.06) / 64,
-    (width * 0.72) / (bounds.width + depth),
-  );
-  const x = width / 2 - (bounds.x + (bounds.width + depth) / 2) * scale;
-  const layers = Array.from({ length: depth }, (_, index) => {
-    const offset = depth - index;
-    return `<use href="#wordmark" transform="translate(${offset} ${offset})" fill="#40535b"/>`;
-  }).join("");
-  return `<defs>
-    ${text}
-    <linearGradient id="letter-face" x2="0" y2="1">
-      <stop stop-color="#ffffff"/><stop offset=".48" stop-color="#e0e9e7"/>
-      <stop offset="1" stop-color="#9eb4ba"/>
-    </linearGradient>
-  </defs>
-  <g transform="translate(${x} ${height * 0.69}) scale(${scale})">
-    <use href="#wordmark" transform="translate(9 12)" fill="#080f14" opacity=".35"/>
-    ${layers}
-    <use href="#wordmark" fill="url(#letter-face)" stroke="#e8f1ed" stroke-opacity=".4" stroke-width=".5"/>
-  </g>`;
-}
+import { isResvgAvailable } from "../avatar/resvg-lazy.js";
+import { resolveWorkerCommand } from "../util/worker-process.js";
 
-export function renderDesktopWallpaper(
-  width: number,
-  height: number,
-  avatar: Buffer | null,
-  accentHex: string | null,
-  assistantName: string | null = null,
-): Buffer {
-  const accent = /^#[\da-f]{6}$/i.test(accentHex ?? "")
-    ? accentHex!
-    : "#91a6b0";
-  const cx = width / 2;
-  const cy = height * 0.46;
-  const size = Math.min(width, height) * 0.24;
-  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}">
-    <defs>
-      <linearGradient id="base" x2="1" y2="1">
-        <stop stop-color="#202a30"/><stop offset="1" stop-color="#10171c"/>
-      </linearGradient>
-      <radialGradient id="glow">
-        <stop stop-color="${accent}" stop-opacity=".24"/>
-        <stop offset="1" stop-color="${accent}" stop-opacity="0"/>
-      </radialGradient>
-      <radialGradient id="shadow">
-        <stop stop-color="#000" stop-opacity=".25"/>
-        <stop offset="1" stop-color="#000" stop-opacity="0"/>
-      </radialGradient>
-    </defs>
-    <path fill="url(#base)" d="M0 0H${width}V${height}H0z"/>
-    <ellipse cx="${cx}" cy="${cy}" rx="${height * 0.7}" ry="${height * 0.6}" fill="url(#glow)"/>
-    <g fill="none" stroke="${accent}">
-      <circle cx="${cx}" cy="${cy}" r="${size * 0.76}" stroke-opacity=".16"/>
-      <circle cx="${cx}" cy="${cy}" r="${size * 1.25}" stroke-opacity=".09"/>
-      <circle cx="${cx}" cy="${cy}" r="${size * 1.9}" stroke-opacity=".05"/>
-    </g>
-    ${
-      avatar
-        ? `<ellipse cx="${cx}" cy="${cy + size * 0.48}" rx="${size * 0.7}" ry="${size * 0.16}" fill="url(#shadow)"/>
-    <image x="${cx - size / 2}" y="${cy - size / 2}" width="${size}" height="${size}" href="data:image/png;base64,${avatar.toString("base64")}"/>`
-        : ""
-    }
-    ${wallpaperWordmark(width, height, assistantName)}
-  </svg>`;
-  const Resvg = getResvg();
-  return Buffer.from(new Resvg(svg).render().asPng());
-}
+const runFile = promisify(execFile);
 
 export async function renderCurrentDesktopWallpaper(
   width: number,
@@ -101,13 +16,30 @@ export async function renderCurrentDesktopWallpaper(
   if (!isResvgAvailable()) {
     return null;
   }
-  const state = readAvatarState();
-  const name = getAssistantName();
-  return renderDesktopWallpaper(
-    width,
-    height,
-    await renderNotificationAvatarPng(state),
-    resolveNotificationAccentHex(state),
-    name,
-  );
+  const directory = await mkdtemp(join(tmpdir(), "vellum-wallpaper-"));
+  const output = join(directory, "wallpaper.png");
+  try {
+    const [executable, ...args] = resolveWorkerCommand(
+      new URL("./desktop-wallpaper-worker.ts", import.meta.url),
+      undefined,
+    );
+    await runFile(
+      executable!,
+      [...args, String(width), String(height), output],
+      {
+        timeout: 30_000,
+        killSignal: "SIGKILL",
+        maxBuffer: 64 * 1024,
+        windowsHide: true,
+      },
+    );
+    return await readFile(output).catch((error: NodeJS.ErrnoException) => {
+      if (error.code === "ENOENT") {
+        return null;
+      }
+      throw error;
+    });
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
 }

package/src/desktop/virtual-desktop-feature.ts

@@ -6,7 +6,7 @@ const VIRTUAL_DESKTOP_FLAG = "assistant-desktop" as const;
 
 /** Gates desktop streaming and control to enabled, platform-hosted containers. */
 export function isVirtualDesktopEnabled(
-  config: AssistantConfig,
+  config?: AssistantConfig,
   containerized: boolean = getIsContainerized(),
   platformHosted: boolean = getIsPlatform(),
 ): boolean {

package/src/mcp/__tests__/manager-tool-caps.test.ts

@@ -0,0 +1,111 @@
+/**
+ * McpServerManager.start() applies the shared fair cap after every
+ * configured server has been attempted in parallel. A slow earlier
+ * server must not prevent later ones from being listed, and later
+ * servers must keep tools when the global cap binds.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { ResolvedMcpConfig } from "../../config/schemas/mcp.js";
+
+const toolsByServer = new Map<string, Array<{ name: string }>>();
+const connectDelays = new Map<string, number>();
+
+mock.module("../client.js", () => ({
+  McpClient: class {
+    constructor(readonly serverId: string) {}
+    get isConnected() {
+      return true;
+    }
+    get lastError() {
+      return null;
+    }
+    async connect() {
+      const delay = connectDelays.get(this.serverId) ?? 0;
+      if (delay > 0) {
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+    async listTools() {
+      return (toolsByServer.get(this.serverId) ?? []).map((tool) => ({
+        name: tool.name,
+        description: `${this.serverId} ${tool.name}`,
+        inputSchema: { type: "object", properties: {} },
+      }));
+    }
+    async disconnect() {}
+  },
+}));
+
+const { McpServerManager } = await import("../manager.js");
+
+function httpServer(): ResolvedMcpConfig["servers"][string] {
+  return {
+    source: "workspace",
+    transport: {
+      type: "streamable-http",
+      url: "https://example.invalid/mcp",
+    },
+  };
+}
+
+function configWith(ids: string[]): ResolvedMcpConfig {
+  return {
+    servers: Object.fromEntries(ids.map((id) => [id, httpServer()])),
+  };
+}
+
+describe("McpServerManager tool selection", () => {
+  beforeEach(() => {
+    toolsByServer.clear();
+    connectDelays.clear();
+  });
+
+  test("later servers keep tools when eight servers exceed the global cap", async () => {
+    const ids = Array.from(
+      { length: 8 },
+      (_, i) => `server-${String(i + 1).padStart(2, "0")}`,
+    );
+    for (const id of ids) {
+      toolsByServer.set(
+        id,
+        Array.from({ length: 10 }, (_, i) => ({ name: `tool_${i}` })),
+      );
+    }
+
+    const manager = new McpServerManager();
+    const started = await manager.start(configWith(ids));
+
+    expect(started.discoveredToolCount).toBe(80);
+    expect(started.keptToolCount).toBe(50);
+    expect(started.truncatedServerIds.length).toBeGreaterThan(0);
+    expect(
+      started.servers.every((server) => server.tools.length > 0),
+      "Fair selection must not empty servers 6-8 merely because they were last.",
+    ).toBe(true);
+    await manager.stop();
+  });
+
+  test("a slow earlier server does not prevent later servers from connecting", async () => {
+    toolsByServer.set("slow", [{ name: "slow_tool" }]);
+    toolsByServer.set("fast", [{ name: "fast_tool" }]);
+    connectDelays.set("slow", 40);
+
+    const manager = new McpServerManager();
+    const startedAt = Date.now();
+    const started = await manager.start(configWith(["slow", "fast"]));
+    const elapsed = Date.now() - startedAt;
+
+    expect(started.connectedServerCount).toBe(2);
+    expect(started.servers.map((server) => server.serverId).sort()).toEqual([
+      "fast",
+      "slow",
+    ]);
+    expect(
+      elapsed < 80,
+      "Servers connect in parallel, so one 40ms delay should not serialize both.",
+    ).toBe(true);
+    await manager.stop();
+  });
+});