@vellumai/assistant 0.8.0 → 0.8.2

package/src/__tests__/oauth-connect-routes.test.ts

@@ -41,6 +41,49 @@ mock.module("../util/logger.js", () => ({
     }),
 }));
 
+// ── Mock oauth-store so handleOAuthConnectStart can run without a seeded DB ──
+type MockProviderRow = {
+  authorizeUrl?: string;
+  requiresClientSecret?: boolean;
+  [key: string]: unknown;
+};
+
+const DEFAULT_PROVIDER: MockProviderRow = {
+  authorizeUrl: "https://accounts.google.com/o/oauth2/auth",
+  requiresClientSecret: false,
+};
+
+let mockGetProvider: (service: string) => MockProviderRow | undefined = () =>
+  DEFAULT_PROVIDER;
+let mockGetAppByProviderAndClientId: (
+  service: string,
+  clientId: string,
+) => Record<string, unknown> | undefined = (_service, clientId) => ({
+  id: "test-app-id",
+  provider: "google",
+  clientId,
+});
+let mockGetMostRecentAppByProvider: (
+  service: string,
+) => Record<string, unknown> | undefined = () => ({
+  id: "test-app-id",
+  provider: "google",
+  clientId: "default-client-id",
+});
+let mockGetAppClientSecret: (
+  row: Record<string, unknown>,
+) => Promise<string | undefined> = async () => undefined;
+
+mock.module("../oauth/oauth-store.js", () => ({
+  getProvider: (service: string) => mockGetProvider(service),
+  getAppByProviderAndClientId: (service: string, clientId: string) =>
+    mockGetAppByProviderAndClientId(service, clientId),
+  getMostRecentAppByProvider: (service: string) =>
+    mockGetMostRecentAppByProvider(service),
+  getAppClientSecret: (row: Record<string, unknown>) =>
+    mockGetAppClientSecret(row),
+}));
+
 // NOTE: Do NOT mock oauth-connect-state — use the real module so we can
 // verify state transitions via getOAuthConnectState.
 
@@ -65,6 +108,23 @@ function findRoute(operationId: string) {
 // ── Tests ──────────────────────────────────────────────────────────────────────
 
 describe("oauth-connect-routes", () => {
+  beforeEach(() => {
+    // Reset oauth-store mocks to permissive defaults so every test starts
+    // from a clean baseline regardless of what the previous test set.
+    mockGetProvider = () => DEFAULT_PROVIDER;
+    mockGetAppByProviderAndClientId = (_service, clientId) => ({
+      id: "test-app-id",
+      provider: "google",
+      clientId,
+    });
+    mockGetMostRecentAppByProvider = () => ({
+      id: "test-app-id",
+      provider: "google",
+      clientId: "default-client-id",
+    });
+    mockGetAppClientSecret = async () => undefined;
+  });
+
   describe("POST internal/oauth/connect/start", () => {
     beforeEach(() => {
       capturedOnDeferredComplete = undefined;
@@ -109,17 +169,6 @@ describe("oauth-connect-routes", () => {
       ).rejects.toBeInstanceOf(BadRequestError);
     });
 
-    test("missing clientId throws BadRequestError", async () => {
-      await expect(
-        findRoute("internal_oauth_connect_start").handler({
-          body: {
-            service: "google",
-            callbackTransport: "gateway",
-          },
-        }),
-      ).rejects.toBeInstanceOf(BadRequestError);
-    });
-
     test("missing service throws BadRequestError", async () => {
       await expect(
         findRoute("internal_oauth_connect_start").handler({
@@ -183,6 +232,120 @@ describe("oauth-connect-routes", () => {
         }),
       ).rejects.toBeInstanceOf(InternalError);
     });
+
+    test("unknown provider throws NotFoundError", async () => {
+      mockGetProvider = () => undefined;
+      await expect(
+        findRoute("internal_oauth_connect_start").handler({
+          body: {
+            service: "made-up-service",
+            clientId: "my-client-id",
+            callbackTransport: "gateway",
+          },
+        }),
+      ).rejects.toBeInstanceOf(NotFoundError);
+    });
+
+    test("manual-token provider rejected even when clientId is explicitly supplied", async () => {
+      // Codex/Devin finding on PR #30251: the manual-token check used to live
+      // inside `if (!clientId)`, so callers passing `--client-id` for a
+      // manual-token provider (e.g. slack_channel, telegram) bypassed it.
+      mockGetProvider = () => ({
+        authorizeUrl: "urn:manual-token",
+        requiresClientSecret: false,
+      });
+      await expect(
+        findRoute("internal_oauth_connect_start").handler({
+          body: {
+            service: "slack_channel",
+            clientId: "any-client-id",
+            callbackTransport: "gateway",
+          },
+        }),
+      ).rejects.toBeInstanceOf(BadRequestError);
+    });
+
+    test("manual-token provider rejected when no clientId is supplied", async () => {
+      mockGetProvider = () => ({
+        authorizeUrl: "urn:manual-token",
+        requiresClientSecret: false,
+      });
+      await expect(
+        findRoute("internal_oauth_connect_start").handler({
+          body: {
+            service: "slack_channel",
+            callbackTransport: "gateway",
+          },
+        }),
+      ).rejects.toBeInstanceOf(BadRequestError);
+    });
+
+    test("explicit clientId with no registered app throws NotFoundError", async () => {
+      // Devin finding on PR #30251: the explicit-clientId branch used to
+      // silently continue when getAppByProviderAndClientId returned null,
+      // letting orchestrateOAuthConnect fail later with a less helpful error.
+      mockGetAppByProviderAndClientId = () => undefined;
+      await expect(
+        findRoute("internal_oauth_connect_start").handler({
+          body: {
+            service: "google",
+            clientId: "unregistered-client-id",
+            callbackTransport: "gateway",
+          },
+        }),
+      ).rejects.toBeInstanceOf(NotFoundError);
+    });
+
+    test("no clientId and no registered app throws BadRequestError", async () => {
+      mockGetMostRecentAppByProvider = () => undefined;
+      await expect(
+        findRoute("internal_oauth_connect_start").handler({
+          body: {
+            service: "google",
+            callbackTransport: "gateway",
+          },
+        }),
+      ).rejects.toBeInstanceOf(BadRequestError);
+    });
+
+    test("missing client_secret when provider requiresClientSecret throws BadRequestError", async () => {
+      // Devin finding on PR #30251: requiresClientSecret was only checked
+      // inside the `!clientId` branch. Hoisting it ensures explicit-clientId
+      // callers also fail fast with an actionable error.
+      mockGetProvider = () => ({
+        authorizeUrl: "https://accounts.example.com/o/oauth2/auth",
+        requiresClientSecret: true,
+      });
+      mockGetAppClientSecret = async () => undefined;
+      await expect(
+        findRoute("internal_oauth_connect_start").handler({
+          body: {
+            service: "github",
+            clientId: "explicit-client-id",
+            callbackTransport: "gateway",
+          },
+        }),
+      ).rejects.toBeInstanceOf(BadRequestError);
+    });
+
+    test("explicit clientId + stored secret succeeds without caller-supplied secret", async () => {
+      mockGetProvider = () => ({
+        authorizeUrl: "https://accounts.example.com/o/oauth2/auth",
+        requiresClientSecret: true,
+      });
+      mockGetAppClientSecret = async () => "stored-secret-from-keyring";
+      const result = await findRoute("internal_oauth_connect_start").handler({
+        body: {
+          service: "github",
+          clientId: "explicit-client-id",
+          callbackTransport: "gateway",
+        },
+      });
+      expect(result).toMatchObject({
+        auth_url: "https://accounts.google.com/o/oauth2/auth?client_id=test",
+        state: "test-state-uuid-abc123",
+      });
+    });
   });
 
   describe("GET internal/oauth/connect/status/:state", () => {

package/src/__tests__/oauth-provider-profiles.test.ts

@@ -21,6 +21,15 @@ initializeDb();
 seedOAuthProviders();
 
 describe("oauth provider profiles (DB-seeded)", () => {
+  test("google provider row includes Drive in default scopes", () => {
+    const provider = getProvider("google");
+
+    expect(provider).toBeDefined();
+    expect(JSON.parse(provider!.defaultScopes)).toContain(
+      "https://www.googleapis.com/auth/drive",
+    );
+  });
+
   test("google provider row contains bearer injection templates for 3 Google API hosts", () => {
     const provider = getProvider("google");
 

package/src/__tests__/oauth-providers-routes.test.ts

@@ -245,22 +245,26 @@ describe("GET /v1/oauth/providers/:providerKey", () => {
     );
 
     expect(status).toBe(200);
+    // The GET-by-key endpoint uses `serializeProviderFull`, which intentionally
+    // emits camelCase keys (see provider-serializer.ts). The list endpoint
+    // uses `serializeProviderSummary` and emits snake_case — these are
+    // separate wire formats by design.
     const { provider } = body as {
       provider: {
-        provider_key: string;
-        display_name: string | null;
+        providerKey: string;
+        displayName: string | null;
         description: string | null;
-        dashboard_url: string | null;
-        client_id_placeholder: string | null;
-        requires_client_secret: boolean;
-        supports_managed_mode: boolean;
+        dashboardUrl: string | null;
+        clientIdPlaceholder: string | null;
+        requiresClientSecret: boolean;
+        supportsManagedMode: boolean;
       };
     };
 
-    expect(provider.provider_key).toBe("google");
-    expect(provider.display_name).toBe("Google");
-    expect(provider.supports_managed_mode).toBe(true);
-    expect(provider.requires_client_secret).toBe(true);
+    expect(provider.providerKey).toBe("google");
+    expect(provider.displayName).toBe("Google");
+    expect(provider.supportsManagedMode).toBe(true);
+    expect(provider.requiresClientSecret).toBe(true);
   });
 
   test("returns 404 for unknown provider", async () => {

package/src/__tests__/openai-provider.test.ts

@@ -1344,6 +1344,30 @@ describe("OpenRouterProvider reasoning", () => {
     expect(lastCreateParams!.reasoning).toEqual({ enabled: false });
   });
 
+  test("sends OpenRouter app-attribution headers on OpenAI-compatible requests", async () => {
+    const provider = new OpenRouterProvider("or-key", "x-ai/grok-4");
+    await provider.sendMessage([userMsg("hi")], undefined, undefined, {
+      config: {
+        usageAttributionHeaders: {
+          "Vellum-Organization-Id": "org-123",
+        },
+      },
+    });
+
+    expect(lastCreateOptions?.headers).toEqual(
+      expect.objectContaining({
+        "HTTP-Referer": "https://www.vellum.ai",
+        "X-OpenRouter-Title": "Vellum Assistant",
+        "X-OpenRouter-Categories": "personal-agent,cli-agent",
+        "Vellum-Organization-Id": "org-123",
+      }),
+    );
+    expect(lastCreateParams).not.toHaveProperty("HTTP-Referer");
+    expect(lastCreateParams).not.toHaveProperty("X-OpenRouter-Title");
+    expect(lastCreateParams).not.toHaveProperty("X-OpenRouter-Categories");
+    expect(lastCreateParams).not.toHaveProperty("usageAttributionHeaders");
+  });
+
   test("RetryProvider + OpenRouterProvider enables thinking end-to-end", async () => {
     const provider = new OpenRouterProvider("or-key", "x-ai/grok-4");
     const retry = new RetryProvider(provider);

package/src/__tests__/openai-responses-cutover-guard.test.ts

@@ -13,8 +13,9 @@ import { describe, expect, test } from "bun:test";
  *
  * These guards fail CI if:
  * 1. The Responses provider file contains `chat.completions.create(` calls.
- * 2. The provider registry wires `openai` to anything other than
- *    `OpenAIResponsesProvider`.
+ * 2. The adapter factory wires `openai` to anything other than
+ *    `OpenAIResponsesProvider`. (Catalog-driven adapter construction lives
+ *    in `inference/adapter-factory.ts`; `registry.ts` only orchestrates it.)
  * 3. A new file appears in `providers/openai/` that introduces
  *    `chat.completions.create(` calls.
  *
@@ -40,6 +41,11 @@ import { describe, expect, test } from "bun:test";
 
 const PROVIDERS_DIR = join(import.meta.dir, "..", "providers");
 const OPENAI_PROVIDERS_DIR = join(PROVIDERS_DIR, "openai");
+const ADAPTER_FACTORY_PATH = join(
+  PROVIDERS_DIR,
+  "inference",
+  "adapter-factory.ts",
+);
 
 describe("OpenAI Responses API cutover guard", () => {
   test("responses-provider.ts does not contain chat.completions.create() calls", () => {
@@ -60,43 +66,66 @@ describe("OpenAI Responses API cutover guard", () => {
     ).toBe(false);
   });
 
-  test("registry.ts wires the 'openai' provider to OpenAIResponsesProvider", () => {
-    const source = readFileSync(join(PROVIDERS_DIR, "registry.ts"), "utf-8");
+  test("adapter-factory.ts wires the 'openai' provider to OpenAIResponsesProvider", () => {
+    // Catalog-driven adapter construction lives in `adapter-factory.ts`.
+    // `registry.ts` only orchestrates and wraps the adapter; the only place
+    // that names a provider class for the "openai" id is the factory table.
+    const source = readFileSync(ADAPTER_FACTORY_PATH, "utf-8");
 
-    // The registry should import OpenAIResponsesProvider
+    // The factory must import OpenAIResponsesProvider.
     expect(
       source.includes("OpenAIResponsesProvider"),
-      "registry.ts must import OpenAIResponsesProvider for the openai provider.",
+      "adapter-factory.ts must import OpenAIResponsesProvider for the openai provider.",
     ).toBe(true);
 
-    // The registry should instantiate OpenAIResponsesProvider for the "openai" key.
-    // Look for `new OpenAIResponsesProvider(` near the openai registration block.
+    // The factory must instantiate OpenAIResponsesProvider.
     const hasResponsesInstantiation = source.includes(
       "new OpenAIResponsesProvider(",
     );
     expect(
       hasResponsesInstantiation,
       [
-        "registry.ts must instantiate OpenAIResponsesProvider for the 'openai' provider.",
+        "adapter-factory.ts must instantiate OpenAIResponsesProvider for the 'openai' provider.",
         "OpenAI inference uses the Responses API, not chat completions.",
       ].join("\n"),
     ).toBe(true);
 
-    // The registry should NOT instantiate OpenAIChatCompletionsProvider or
-    // OpenAIProvider (the backward-compatible alias) for the "openai" key.
-    // Chat-completions classes may appear in imports but should not be
-    // instantiated in the openai registration block.
-    const chatCompletionsInstantiations = [
-      ...source.matchAll(/new\s+OpenAIChatCompletionsProvider\s*\(/g),
-      ...source.matchAll(/new\s+OpenAIProvider\s*\(/g),
+    // The factory must NOT instantiate OpenAIChatCompletionsProvider or
+    // OpenAIProvider (the backward-compatible alias) inside the `openai:`
+    // factory entry. Other entries (e.g. `zai:`, `deepseek:`, `minimax:`)
+    // may legitimately use OpenAIChatCompletionsProvider since that's the
+    // OpenAI Chat Completions transport for third-party endpoints.
+    const openaiEntryRegion =
+      /(?:^|\s)openai\s*:\s*\([^)]*\)\s*=>\s*[\s\S]{0,400}?(?=\}\s*,\s*[a-z-]+\s*:|\}\s*;)/m.exec(
+        source,
+      )?.[0] ?? "";
+    const chatCompletionsInstantiationsInOpenAi = [
+      ...openaiEntryRegion.matchAll(
+        /new\s+OpenAIChatCompletionsProvider\s*\(/g,
+      ),
+      ...openaiEntryRegion.matchAll(/new\s+OpenAIProvider\s*\(/g),
     ];
     expect(
-      chatCompletionsInstantiations.length,
+      chatCompletionsInstantiationsInOpenAi.length,
       [
-        "registry.ts must NOT instantiate OpenAIChatCompletionsProvider or",
-        "OpenAIProvider (legacy alias). Use OpenAIResponsesProvider for openai.",
+        "ADAPTER_FACTORIES['openai'] must NOT instantiate",
+        "OpenAIChatCompletionsProvider or OpenAIProvider (legacy alias).",
+        "Use OpenAIResponsesProvider for openai.",
       ].join("\n"),
     ).toBe(0);
+
+    // The factory's "openai" entry must specifically map to OpenAIResponsesProvider.
+    // Match `openai:` followed (within ~400 chars) by `new OpenAIResponsesProvider(`
+    // to confirm wiring at the entry level, not just an unrelated reference.
+    const openaiEntryWiring =
+      /openai\s*:\s*\([^)]*\)\s*=>\s*[\s\S]{0,400}?new\s+OpenAIResponsesProvider\s*\(/;
+    expect(
+      openaiEntryWiring.test(source),
+      [
+        "adapter-factory.ts ADAPTER_FACTORIES['openai'] entry must construct",
+        "OpenAIResponsesProvider. If the factory shape changed, update this guard.",
+      ].join("\n"),
+    ).toBe(true);
   });
 
   test("no files in providers/openai/ introduce chat.completions.create() calls", () => {

package/src/__tests__/openai-responses-provider.test.ts

@@ -677,6 +677,23 @@ describe("OpenAIResponsesProvider", () => {
     expect(lastStreamParams!.text).toEqual({ verbosity: "high" });
   });
 
+  test("verbosity is forwarded for GPT-5 fine-tune IDs", async () => {
+    const ftProvider = new OpenAIResponsesProvider(
+      "sk-test",
+      "ft:gpt-5.2:acme::abc123",
+    );
+    fakeStreamEvents = [textDeltaEvent("OK"), completedEvent(10, 2)];
+
+    await ftProvider.sendMessage(
+      [{ role: "user", content: [{ type: "text", text: "Hi" }] }],
+      undefined,
+      undefined,
+      { config: { verbosity: "low" } },
+    );
+
+    expect(lastStreamParams!.text).toEqual({ verbosity: "low" });
+  });
+
   // -----------------------------------------------------------------------
   // Model override
   // -----------------------------------------------------------------------

package/src/__tests__/overflow-reduce-pipeline.test.ts

@@ -453,7 +453,6 @@ describe("overflow-reduce pipeline", () => {
         manifest: {
           name: "spy-overflow",
           version: "0.0.1",
-          requires: { pluginRuntime: "v1", overflowReduceApi: "v1" },
         },
         middleware: { overflowReduce: spy },
       };
@@ -512,7 +511,6 @@ describe("overflow-reduce pipeline", () => {
         manifest: {
           name: "short-circuit-overflow",
           version: "0.0.1",
-          requires: { pluginRuntime: "v1", overflowReduceApi: "v1" },
         },
         middleware: { overflowReduce: shortCircuit },
       });

package/src/__tests__/persistence-pipeline.test.ts

@@ -267,7 +267,6 @@ describe("persistence pipeline", () => {
       manifest: {
         name: "mock-persistence",
         version: "0.0.1",
-        requires: { pluginRuntime: "v1" },
       },
       middleware: { persistence: redirect },
     };
@@ -352,7 +351,6 @@ describe("persistence pipeline", () => {
       manifest: {
         name: "late-user-plugin",
         version: "0.0.1",
-        requires: { pluginRuntime: "v1" },
       },
       middleware: { persistence: userMiddleware },
     });

package/src/__tests__/{managed-proxy-context.test.ts → platform-proxy-context.test.ts}

@@ -32,7 +32,7 @@ import {
   hasManagedProxyPrereqs,
   managedFallbackEnabledFor,
   resolveManagedProxyContext,
-} from "../providers/managed-proxy/context.js";
+} from "../providers/platform-proxy/context.js";
 
 describe("resolveManagedProxyContext", () => {
   beforeEach(() => {

package/src/__tests__/platform.test.ts

@@ -16,6 +16,7 @@ import {
   getWorkspaceConfigPath,
   getWorkspaceDir,
   getWorkspaceHooksDir,
+  getWorkspacePluginsDir,
   getWorkspacePromptPath,
   getWorkspaceSkillsDir,
   getXdgVellumConfigDirName,
@@ -161,6 +162,7 @@ describe("workspace path primitives", () => {
     expect(getWorkspaceConfigPath()).toBe(join(ws, "config.json"));
     expect(getWorkspaceSkillsDir()).toBe(join(ws, "skills"));
     expect(getWorkspaceHooksDir()).toBe(join(ws, "hooks"));
+    expect(getWorkspacePluginsDir()).toBe(join(ws, "plugins"));
     expect(getWorkspacePromptPath("IDENTITY.md")).toBe(join(ws, "IDENTITY.md"));
     expect(getWorkspacePromptPath("SOUL.md")).toBe(join(ws, "SOUL.md"));
   });

package/src/__tests__/plugin-api-shim.test.ts

@@ -0,0 +1,125 @@
+/**
+ * Smoke tests for the workspace-level `@vellumai/plugin-api` shim.
+ *
+ *   - shim files are materialized at `<workspaceDir>/node_modules/@vellumai/plugin-api/`
+ *   - the shim's index.js re-binds each runtime export from globalThis
+ *   - the shim is idempotent across re-runs
+ *   - a fake plugin in `<workspaceDir>/plugins/<name>/` can resolve the
+ *     bare `@vellumai/plugin-api` specifier via Node-style walk-up,
+ *     proving the end-to-end import path works for real user plugins
+ *
+ * As plugin-api's runtime surface grows in follow-up PRs, the shim's
+ * generated export list expands automatically — the test below covers
+ * the generator (`buildShimSource`) directly so we don't need to
+ * update assertions every time an export is added.
+ */
+
+import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "bun:test";
+
+import {
+  PLUGIN_API_EXPORTS,
+  PLUGIN_API_REGISTRY_KEY,
+} from "../embedded/plugin-api.js";
+import {
+  buildShimSource,
+  ensurePluginApiShim,
+} from "../plugins/ensure-plugin-api-shim.js";
+
+const SHIM_REL_PATH = "node_modules/@vellumai/plugin-api";
+
+describe("buildShimSource", () => {
+  test("emits a globalThis trampoline + one binding per export", () => {
+    const source = buildShimSource(
+      ["foo", "bar"],
+      Symbol.for("vellum.plugin-api.v1"),
+    );
+    expect(source).toBe(
+      `const api = globalThis[Symbol.for("vellum.plugin-api.v1")];\n` +
+        `export const foo = api.foo;\n` +
+        `export const bar = api.bar;\n`,
+    );
+  });
+
+  test("handles an empty export list (today's types-only surface)", () => {
+    const source = buildShimSource(
+      [],
+      Symbol.for("vellum.plugin-api.v1"),
+    );
+    expect(source).toBe(
+      `const api = globalThis[Symbol.for("vellum.plugin-api.v1")];\n`,
+    );
+  });
+});
+
+describe("ensurePluginApiShim", () => {
+  test("creates a resolvable @vellumai/plugin-api package under workspaceDir", async () => {
+    const workspaceDir = await mkdtemp(join(tmpdir(), "plugin-api-shim-"));
+    await ensurePluginApiShim({ workspaceDir });
+
+    const shimDir = join(workspaceDir, SHIM_REL_PATH);
+    const indexJs = await readFile(join(shimDir, "index.js"), "utf8");
+    expect(indexJs).toBe(buildShimSource());
+
+    const pkg = JSON.parse(
+      await readFile(join(shimDir, "package.json"), "utf8"),
+    );
+    expect(pkg.name).toBe("@vellumai/plugin-api");
+    expect(pkg.type).toBe("module");
+    expect(pkg.main).toBe("./index.js");
+    expect(typeof pkg.version).toBe("string");
+  });
+
+  test("is idempotent — re-running yields the same shim contents", async () => {
+    const workspaceDir = await mkdtemp(join(tmpdir(), "plugin-api-shim-"));
+    await ensurePluginApiShim({ workspaceDir });
+    const first = await readFile(
+      join(workspaceDir, SHIM_REL_PATH, "index.js"),
+      "utf8",
+    );
+
+    await ensurePluginApiShim({ workspaceDir });
+    const second = await readFile(
+      join(workspaceDir, SHIM_REL_PATH, "index.js"),
+      "utf8",
+    );
+    expect(second).toBe(first);
+  });
+
+  test("globalThis is populated with the plugin-api namespace", () => {
+    // Importing the embed wrapper has the side effect of installing the
+    // namespace on globalThis. By the time this test runs (any earlier
+    // test in the file has already imported it), the registry must be
+    // populated.
+    const namespace = (globalThis as Record<symbol, unknown>)[
+      PLUGIN_API_REGISTRY_KEY
+    ];
+    expect(namespace).toBeDefined();
+    // Exports list is non-null but may be empty until runtime exports
+    // migrate in later PRs.
+    expect(Array.isArray(PLUGIN_API_EXPORTS)).toBe(true);
+  });
+
+  test("a fake user plugin can resolve @vellumai/plugin-api via Node-style walk-up", async () => {
+    const workspaceDir = await mkdtemp(join(tmpdir(), "plugin-api-shim-"));
+    await ensurePluginApiShim({ workspaceDir });
+
+    const pluginDir = join(workspaceDir, "plugins", "fake-plugin");
+    await mkdir(pluginDir, { recursive: true });
+    await writeFile(
+      join(pluginDir, "register.js"),
+      `import * as api from "@vellumai/plugin-api";\nexport { api };\n`,
+    );
+
+    // Resolution walks up: plugins/fake-plugin → plugins → workspaceDir
+    // → workspaceDir/node_modules/@vellumai/plugin-api → shim → globalThis
+    // → plugin-api namespace. If any link in that chain is broken, this
+    // import throws.
+    const mod: { api: Record<string, unknown> } = await import(
+      join(pluginDir, "register.js")
+    );
+    expect(mod.api).toBeDefined();
+  });
+});