@vellumai/assistant 0.11.2-dev.202608071425.368249e → 0.11.2-dev.202608071521.2d2f93e

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.11.2-dev.202608071425.368249e",
+  "version": "0.11.2-dev.202608071521.2d2f93e",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/events-dev-bypass-actor.test.ts

@@ -27,6 +27,10 @@ let fakeGuardianPrincipalId: string | undefined = undefined;
 // exactly when the SSE self-heal lookup completes.
 const pendingAsyncResolutions: Array<(value: string | undefined) => void> = [];
 
+/** Options each async resolution was called with, in the same order. */
+const asyncResolutionOptions: Array<{ forceRefresh?: boolean } | undefined> =
+  [];
+
 mock.module("../config/env.js", () => ({
   isHttpAuthDisabled: () => fakeHttpAuthDisabled,
   hasUngatedHttpAuthDisabled: () => false,
@@ -42,10 +46,14 @@ mock.module("../runtime/local-actor-identity.js", () => ({
     }
     return fakeGuardianPrincipalId;
   },
-  resolveActorPrincipalIdForLocalGuardian: (rawHeader: string | undefined) => {
+  resolveActorPrincipalIdForLocalGuardian: (
+    rawHeader: string | undefined,
+    options?: { forceRefresh?: boolean },
+  ) => {
     if (rawHeader !== "dev-bypass" || !fakeHttpAuthDisabled) {
       return Promise.resolve(rawHeader);
     }
+    asyncResolutionOptions.push(options);
     return new Promise<string | undefined>((resolve) => {
       pendingAsyncResolutions.push(resolve);
     });
@@ -57,6 +65,23 @@ async function flushMicrotasks(): Promise<void> {
   await new Promise((resolve) => setTimeout(resolve, 0));
 }
 
+/**
+ * Poll until `predicate` holds, for assertions that depend on the heal's
+ * retry backoff timer rather than on promise settling alone.
+ */
+async function waitFor(
+  predicate: () => boolean,
+  timeoutMs = 3_000,
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (!predicate()) {
+    if (Date.now() >= deadline) {
+      throw new Error("waitFor timed out");
+    }
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+}
+
 // ── Real imports (after mocks) ────────────────────────────────────────────
 
 import { AssistantEventHub } from "../runtime/assistant-event-hub.js";
@@ -69,6 +94,7 @@ afterAll(() => {
 describe("events SSE registration — dev-bypass actor translation", () => {
   beforeEach(() => {
     pendingAsyncResolutions.length = 0;
+    asyncResolutionOptions.length = 0;
   });
 
   test("translates 'dev-bypass' to the real guardian principalId when auth is disabled", () => {
@@ -261,6 +287,91 @@ describe("events SSE registration — dev-bypass actor translation", () => {
     ac2.abort();
   });
 
+  test("retries the heal after a failed lookup instead of giving up for the connection's lifetime", async () => {
+    // The gateway IPC returns null on any transport failure, so the first
+    // lookup can miss even when a guardian is bound. A subscription left
+    // principal-less rejects every host-proxy result it submits, so the heal
+    // has to outlive one miss rather than stopping there.
+    fakeHttpAuthDisabled = true;
+    fakeGuardianPrincipalId = undefined; // cold cache: sync resolution misses
+
+    const ac = new AbortController();
+    const hub = new AssistantEventHub();
+
+    handleSubscribeAssistantEvents(
+      {
+        headers: {
+          "x-vellum-client-id": "retry-client-001",
+          "x-vellum-interface-id": "chrome-extension",
+          "x-vellum-actor-principal-id": "dev-bypass",
+        },
+        abortSignal: ac.signal,
+      },
+      { hub },
+    );
+
+    // First attempt fails (gateway not reachable yet).
+    expect(pendingAsyncResolutions).toHaveLength(1);
+    pendingAsyncResolutions.shift()!(undefined);
+    await flushMicrotasks();
+    expect(
+      hub.getActorPrincipalIdForClient("retry-client-001"),
+    ).toBeUndefined();
+
+    // The retry fires on the backoff and succeeds this time.
+    await waitFor(() => pendingAsyncResolutions.length === 1);
+    pendingAsyncResolutions.shift()!("guardian-real-id");
+    await flushMicrotasks();
+
+    expect(hub.getActorPrincipalIdForClient("retry-client-001")).toBe(
+      "guardian-real-id",
+    );
+
+    // Every attempt must bypass the guardian-delivery cache. A successful read
+    // that finds no binding is cached for minutes, which outlives the retry
+    // schedule, so a cached read would spend all attempts on the same answer
+    // and never observe a binding created in between.
+    expect(asyncResolutionOptions).toEqual([
+      { forceRefresh: true },
+      { forceRefresh: true },
+    ]);
+
+    ac.abort();
+  });
+
+  test("needsActorPrincipalHeal reports only live, principal-less client subscriptions", () => {
+    const hub = new AssistantEventHub();
+    const bare = hub.subscribe({
+      type: "client",
+      clientId: "needs-heal-001",
+      interfaceId: "chrome-extension",
+      capabilities: [],
+      callback: () => {},
+    });
+    const withPrincipal = hub.subscribe({
+      type: "client",
+      clientId: "needs-heal-002",
+      interfaceId: "macos",
+      capabilities: [],
+      actorPrincipalId: "guardian-real-id",
+      callback: () => {},
+    });
+    const process = hub.subscribe({ type: "process", callback: () => {} });
+
+    expect(hub.needsActorPrincipalHeal(bare.connectionId)).toBe(true);
+    expect(hub.needsActorPrincipalHeal(withPrincipal.connectionId)).toBe(false);
+    expect(hub.needsActorPrincipalHeal(process.connectionId)).toBe(false);
+    expect(hub.needsActorPrincipalHeal("conn-does-not-exist")).toBe(false);
+
+    // A disposed connection stops needing a heal, which is what ends the
+    // retry loop when a client disconnects mid-backoff.
+    bare.dispose();
+    expect(hub.needsActorPrincipalHeal(bare.connectionId)).toBe(false);
+
+    withPrincipal.dispose();
+    process.dispose();
+  });
+
   test("fillClientActorPrincipalId never overwrites a present principal", () => {
     const hub = new AssistantEventHub();
     const sub = hub.subscribe({

package/src/__tests__/mcp-list-plugin-servers.test.ts

@@ -0,0 +1,250 @@
+/**
+ * Route-level coverage for plugin-declared MCP servers appearing in
+ * `internal_mcp_list` (what `assistant mcp list` renders).
+ *
+ * The unit tests in `plugins/__tests__/mcp-servers.test.ts` cover reading
+ * `mcp.json`. This file covers the merge, and two properties that a
+ * refactor could quietly break:
+ *
+ * 1. A workspace entry of the same id wins. Getting precedence backwards
+ *    would let a plugin redirect a server the user configured by hand.
+ * 2. A plugin server is never health-checked. `McpClient.connect` resolves
+ *    `mcp:<serverId>:headers` and `mcp:<serverId>:tokens` from the
+ *    credential store, and a plugin controls both its server key and its
+ *    URL, so probing one would send a workspace credential to an endpoint
+ *    the plugin chose whenever an id happens to match a stored key.
+ */
+
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { beforeEach, describe, expect, jest, mock, test } from "bun:test";
+
+const mockConnect = jest.fn();
+const mockDisconnect = jest.fn();
+/** Server ids the route actually constructed an MCP client for. */
+const connectedServerIds: string[] = [];
+
+mock.module("../mcp/client.js", () => ({
+  McpClient: class {
+    constructor(serverId: string) {
+      connectedServerIds.push(serverId);
+    }
+    get isConnected() {
+      return true;
+    }
+    get lastError() {
+      return null;
+    }
+    connect = mockConnect;
+    disconnect = mockDisconnect;
+  },
+}));
+
+mock.module("../mcp/mcp-auth-orchestrator.js", () => ({
+  orchestrateMcpOAuthConnect: async () => ({
+    auth_url: "",
+    already_authenticated: false,
+  }),
+}));
+
+mock.module("../mcp/mcp-auth-state.js", () => ({
+  getMcpAuthState: () => null,
+}));
+
+mock.module("../mcp/mcp-oauth-provider.js", () => ({
+  // Stand in for a credential store that holds tokens for every id, which
+  // is the condition under which a leak would be observable.
+  hasMcpOAuthTokens: async () => true,
+  deleteMcpOAuthCredentials: async () => ({ ok: true, failedKeys: [] }),
+}));
+
+mock.module("../mcp/mcp-header-store.js", () => ({
+  getMcpHeaders: async () => ({ Authorization: "Bearer workspace-secret" }),
+  setMcpHeaders: async () => {},
+  deleteMcpHeaders: async () => true,
+}));
+
+mock.module("../daemon/mcp-reload-service.js", () => ({
+  reloadMcpServers: async () => {},
+}));
+
+import { setConfig } from "./helpers/set-config.js";
+
+setConfig("mcp", {
+  servers: {
+    "from-workspace": {
+      transport: { type: "streamable-http", url: "https://config.example/mcp" },
+      enabled: true,
+      defaultRiskLevel: "high",
+      maxTools: 20,
+    },
+    // Deliberately shares an id with the `shadowed` plugin below.
+    shadowed: {
+      transport: { type: "streamable-http", url: "https://wins.example/mcp" },
+      enabled: true,
+      defaultRiskLevel: "low",
+      maxTools: 20,
+    },
+  },
+});
+
+const { getWorkspacePluginsDir } = await import("../util/platform.js");
+const { ROUTES } = await import("../runtime/routes/mcp-auth-routes.js");
+
+const listHandler = ROUTES.find(
+  (r: { operationId: string }) => r.operationId === "internal_mcp_list",
+)!.handler;
+
+interface ListedServer {
+  id: string;
+  status: string;
+  source?: "workspace" | "plugin";
+  pluginName?: string;
+  defaultRiskLevel: string;
+  hasOAuth: boolean;
+  hasStaticAuth: boolean;
+  authType: string;
+  transport: { type: string; url?: string };
+}
+
+function writePlugin(name: string, mcpJson: unknown): void {
+  const dir = join(getWorkspacePluginsDir(), name);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "package.json"),
+    JSON.stringify({ name, version: "1.0.0" }),
+  );
+  writeFileSync(join(dir, "mcp.json"), JSON.stringify(mcpJson));
+}
+
+function unabyssManifest(): unknown {
+  return {
+    mcpServers: {
+      unabyss: { type: "streamable-http", url: "https://mcp.unabyss.com" },
+    },
+  };
+}
+
+async function listServers(): Promise<ListedServer[]> {
+  const result = (await listHandler({})) as { servers: ListedServer[] };
+  return result.servers;
+}
+
+describe("internal_mcp_list, plugin-declared servers", () => {
+  beforeEach(() => {
+    mockConnect.mockReset();
+    mockDisconnect.mockReset();
+    connectedServerIds.length = 0;
+    rmSync(getWorkspacePluginsDir(), { recursive: true, force: true });
+    mkdirSync(getWorkspacePluginsDir(), { recursive: true });
+  });
+
+  test("a plugin's mcp.json server appears alongside workspace servers", async () => {
+    writePlugin("unabyss", unabyssManifest());
+
+    const ids = (await listServers()).map((s) => s.id);
+    expect(ids).toContain("from-workspace");
+    expect(ids).toContain("unabyss");
+  });
+
+  test("plugin servers are labelled with their origin, workspace servers are not", async () => {
+    writePlugin("unabyss", unabyssManifest());
+
+    const servers = await listServers();
+    const plugin = servers.find((s) => s.id === "unabyss")!;
+    const workspace = servers.find((s) => s.id === "from-workspace")!;
+
+    expect(plugin.source).toEqual("plugin");
+    expect(plugin.pluginName).toEqual("unabyss");
+    expect(workspace.source).toEqual("workspace");
+    expect(workspace.pluginName).toBeUndefined();
+  });
+
+  test("a workspace server of the same id wins over the plugin's", async () => {
+    writePlugin("shadowed", {
+      mcpServers: {
+        shadowed: { type: "streamable-http", url: "https://loses.example/mcp" },
+      },
+    });
+
+    const matches = (await listServers()).filter((s) => s.id === "shadowed");
+
+    expect(matches).toHaveLength(1);
+    expect(matches[0].source).toEqual("workspace");
+    expect(matches[0].transport.url).toEqual("https://wins.example/mcp");
+  });
+
+  test("plugin servers are not health-checked, so no credential can reach them", async () => {
+    writePlugin("unabyss", unabyssManifest());
+
+    const servers = await listServers();
+
+    expect(servers.find((s) => s.id === "unabyss")!.status).toEqual("declared");
+    // The credential mocks above return a token and an Authorization header
+    // for every id. Constructing a client for the plugin server is what
+    // would ship them to the plugin-declared URL.
+    expect(connectedServerIds).toContain("from-workspace");
+    expect(connectedServerIds).not.toContain("unabyss");
+  });
+
+  test("plugin servers report no assistant-owned auth even when the store has some", async () => {
+    writePlugin("unabyss", unabyssManifest());
+
+    const plugin = (await listServers()).find((s) => s.id === "unabyss")!;
+    expect(plugin.hasOAuth).toBe(false);
+    expect(plugin.hasStaticAuth).toBe(false);
+    expect(plugin.authType).toEqual("none");
+  });
+
+  test("workspace servers keep reporting their auth state", async () => {
+    const workspace = (await listServers()).find(
+      (s) => s.id === "from-workspace",
+    )!;
+    expect(workspace.hasOAuth).toBe(true);
+    expect(workspace.hasStaticAuth).toBe(true);
+  });
+
+  test("plugin servers default to high risk", async () => {
+    writePlugin("unabyss", unabyssManifest());
+
+    const servers = await listServers();
+    expect(servers.find((s) => s.id === "unabyss")!.defaultRiskLevel).toEqual(
+      "high",
+    );
+  });
+
+  test("a directory with no valid package.json is not advertised", async () => {
+    // The runtime loader would never load it, and its stdio command must
+    // not be reachable through the listing.
+    const dir = join(getWorkspacePluginsDir(), "no-manifest");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(
+      join(dir, "mcp.json"),
+      JSON.stringify({
+        mcpServers: { evil: { type: "stdio", command: "touch" } },
+      }),
+    );
+
+    const ids = (await listServers()).map((s) => s.id);
+    expect(ids).not.toContain("no-manifest__evil");
+    expect(ids).toContain("from-workspace");
+  });
+
+  test("a malformed plugin manifest does not remove workspace servers", async () => {
+    const dir = join(getWorkspacePluginsDir(), "broken");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(
+      join(dir, "package.json"),
+      JSON.stringify({ name: "broken", version: "1.0.0" }),
+    );
+    writeFileSync(join(dir, "mcp.json"), "{ not json");
+
+    const ids = (await listServers()).map((s) => s.id);
+    expect(ids).toContain("from-workspace");
+  });
+
+  test("no plugins installed leaves the listing unchanged", async () => {
+    const servers = await listServers();
+    expect(servers.every((s) => s.source === "workspace")).toBe(true);
+  });
+});

package/src/cli/commands/mcp.help.ts

@@ -7,7 +7,8 @@ export const mcpHelp: CliCommandHelp = {
   description: "Manage MCP (Model Context Protocol) servers",
   helpText: `
 MCP servers extend the assistant's capabilities with external tools. Servers
-are configured in the assistant's config.json under the mcp.servers key. Each
+are configured in the assistant's config.json under the mcp.servers key, or
+declared by an installed plugin in its root mcp.json. Each
 server uses one of three transport types:
 
   stdio             Local process communicating over stdin/stdout
@@ -28,13 +29,21 @@ Examples:
       description: "List configured MCP servers and their status",
       options: [{ flags: "--json", description: "Output as JSON" }],
       helpText: `
-Shows each configured MCP server with its current status and configuration:
+Shows each MCP server with its current status and configuration. Servers come
+from two places: the mcp.servers key in config.json, and the root mcp.json of
+any installed plugin that declares one.
 
-  Name         The server identifier used in config.json
-  Status       Health check result:
+  Name         The server identifier
+  Status       Health check result for workspace servers:
                  ✓  Connected and responding
                  ✗  Error or disabled
                  !  Needs authentication (OAuth required)
+               Plugin-declared servers report "declared" instead. They are
+               listed but not connected by the assistant, and they are not
+               health-checked, so no stored credential can reach a URL a
+               plugin chose.
+  Source       Shown only for plugin-declared servers, naming the plugin.
+               Servers from config.json print no Source line.
   Transport    stdio, sse, or streamable-http
   URL/Command  The server URL (sse/streamable-http) or command (stdio)
   Risk         Default risk level: low, medium, or high

package/src/cli/commands/mcp.ts

@@ -24,6 +24,10 @@ interface McpServerEntry {
   defaultRiskLevel: string;
   allowedTools?: string[];
   blockedTools?: string[];
+  /** Workspace `config.json` or a plugin's `mcp.json`. */
+  source?: "workspace" | "plugin";
+  /** Plugin that declared the server, when `source` is `plugin`. */
+  pluginName?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -81,6 +85,11 @@ async function pollMcpAuthStatus(
 function printServerEntry(entry: McpServerEntry): void {
   log.info(`  ${entry.id}`);
   log.info(`    Status:    ${entry.status}`);
+  // Only plugin-declared servers name a source. A workspace server is the
+  // default case and printing "workspace" on every one of them is noise.
+  if (entry.source === "plugin") {
+    log.info(`    Source:    plugin (${entry.pluginName ?? "unknown"})`);
+  }
   log.info(`    Transport: ${entry.transport?.type ?? "unknown"}`);
   if (entry.transport?.type === "stdio") {
     log.info(