@vellumai/assistant 0.8.9-staging.2 → 0.8.9-staging.4

package/src/__tests__/conversation-tool-setup-app-refresh.test.ts

@@ -2,9 +2,9 @@
  * Regression tests for app surface refresh and eventing side effects in
  * createToolExecutor (conversation-tool-setup.ts).
  *
- * Tests verify that app_refresh, app_create, and app_delete hooks fire
- * correctly, and that removed hooks (app_update, app_file_edit,
- * app_file_write) no longer trigger side effects.
+ * Tests verify that app_refresh, app_update, app_create, and app_delete hooks
+ * fire correctly, and that non-hooked tools (app_file_edit, app_file_write) do
+ * not trigger side effects.
  *
  * File-change detection for file_write/file_edit is handled by
  * AppSourceWatcher (see app-source-watcher.test.ts).
@@ -248,6 +248,76 @@ describe("session-tool-setup app refresh side effects", () => {
     });
   });
 
+  // ── app_update ──────────────────────────────────────────────────────
+
+  describe("app_update", () => {
+    test("triggers refreshSurfacesForApp and broadcast on success", async () => {
+      const ctx = makeCtx();
+      const executor = makeFakeExecutor({
+        content: '{"updated":true,"appId":"app-7"}',
+        isError: false,
+      });
+
+      const toolFn = createToolExecutor(
+        executor as unknown as ToolExecutor,
+        noopPrompter,
+        noopSecretPrompter,
+        ctx,
+        noopLifecycleHandler,
+      );
+
+      await toolFn("app_update", { app_id: "app-7" });
+
+      expect(refreshSpy).toHaveBeenCalledTimes(1);
+      expect((refreshSpy.mock.calls as unknown[][])[0][1]).toBe("app-7");
+      expectAppChangeBroadcast("app-7");
+      expect(updatePublishedSpy).toHaveBeenCalledTimes(1);
+      expect((updatePublishedSpy.mock.calls as unknown[][])[0][0]).toBe(
+        "app-7",
+      );
+    });
+
+    test("skips side effects when result is an error", async () => {
+      const ctx = makeCtx();
+      const executor = makeFakeExecutor({
+        content: "Error: not found",
+        isError: true,
+      });
+
+      const toolFn = createToolExecutor(
+        executor as unknown as ToolExecutor,
+        noopPrompter,
+        noopSecretPrompter,
+        ctx,
+        noopLifecycleHandler,
+      );
+
+      await toolFn("app_update", { app_id: "app-err" });
+
+      expect(refreshSpy).not.toHaveBeenCalled();
+      expect(broadcastSpy).not.toHaveBeenCalled();
+      expect(updatePublishedSpy).not.toHaveBeenCalled();
+    });
+
+    test("skips side effects when app_id is missing", async () => {
+      const ctx = makeCtx();
+      const executor = makeFakeExecutor({ content: "{}", isError: false });
+
+      const toolFn = createToolExecutor(
+        executor as unknown as ToolExecutor,
+        noopPrompter,
+        noopSecretPrompter,
+        ctx,
+        noopLifecycleHandler,
+      );
+
+      await toolFn("app_update", {});
+
+      expect(refreshSpy).not.toHaveBeenCalled();
+      expect(broadcastSpy).not.toHaveBeenCalled();
+    });
+  });
+
   // ── app_create side effects ─────────────────────────────────────────
 
   describe("app_create side effects", () => {
@@ -518,7 +588,6 @@ describe("session-tool-setup app refresh side effects", () => {
         "write_file",
         "shell",
         "app_list",
-        "app_update",
         "app_file_edit",
         "app_file_write",
       ]) {

package/src/__tests__/conversation-undo.test.ts

@@ -1,10 +1,10 @@
 import { describe, expect, test } from "bun:test";
 
+import { findLastUndoableUserMessageIndex } from "../daemon/conversation.js";
 import {
   CONTEXT_SUMMARY_MARKER,
   createContextSummaryMessage,
-} from "../context/window-manager.js";
-import { findLastUndoableUserMessageIndex } from "../daemon/conversation.js";
+} from "../plugins/defaults/compaction/window-manager.js";
 import type { Message } from "../providers/types.js";
 
 function textMessage(role: "user" | "assistant", text: string): Message {

package/src/__tests__/conversation-workspace-cache-state.test.ts

@@ -137,7 +137,7 @@ mock.module("../memory/retrieval-budget.js", () => ({
   computeRecallBudget: () => 0,
 }));
 
-mock.module("../context/window-manager.js", () => ({
+mock.module("../plugins/defaults/compaction/window-manager.js", () => ({
   ContextWindowManager: class {
     constructor() {}
     updateConfig() {}

package/src/__tests__/conversation-workspace-injection.test.ts

@@ -181,7 +181,7 @@ mock.module("../memory/query-builder.js", () => ({
 mock.module("../memory/retrieval-budget.js", () => ({
   computeRecallBudget: () => 0,
 }));
-mock.module("../context/window-manager.js", () => ({
+mock.module("../plugins/defaults/compaction/window-manager.js", () => ({
   ContextWindowManager: class {
     updateConfig() {}
     shouldCompact() {

package/src/__tests__/conversation-workspace-tool-tracking.test.ts

@@ -178,7 +178,7 @@ mock.module("../memory/query-builder.js", () => ({
 mock.module("../memory/retrieval-budget.js", () => ({
   computeRecallBudget: () => 0,
 }));
-mock.module("../context/window-manager.js", () => ({
+mock.module("../plugins/defaults/compaction/window-manager.js", () => ({
   ContextWindowManager: class {
     updateConfig() {}
     shouldCompact() {

package/src/__tests__/credential-security-invariants.test.ts

@@ -230,6 +230,7 @@ describe("Invariant 2: no generic plaintext secret read API", () => {
       "runtime/routes/platform-routes.ts", // CLI platform connect/disconnect/status routes (CLI-migrated to IPC)
       "ipc/skill-routes/providers.ts", // host.providers.secureKeys.getProviderKey IPC route (out-of-process SkillHost companion)
       "daemon/external-plugins-bootstrap.ts", // reads credentials at plugin init (manifest.requiresCredential) via the CES-mediated getSecureKeyAsync path
+      "plugins/external-api.ts", // globalThis runtime bridge that exposes getSecureKeyAsync to dynamically-imported workspace plugins (compiled-binary plugin loading)
       "inbound/platform-callback-registration.ts", // managed credential lookup for platform base URL, assistant ID, and API key
       "tts/providers/elevenlabs-provider.ts", // ElevenLabs TTS API key lookup
       "tts/providers/deepgram-provider.ts", // Deepgram TTS API key lookup

package/src/__tests__/cu-unified-flow.test.ts

@@ -69,6 +69,7 @@ type SurfaceConversationContext =
 function buildMockContext(
   hostCuProxy?: InstanceType<typeof HostCuProxy>,
   trustGuardianPrincipalId: string | null = DEFAULT_PRINCIPAL,
+  actorPrincipalId: string | null = trustGuardianPrincipalId,
 ): SurfaceConversationContext {
   return {
     conversationId: "test-session",
@@ -80,6 +81,16 @@ function buildMockContext(
             guardianPrincipalId: trustGuardianPrincipalId,
           }
         : undefined,
+    authContext:
+      actorPrincipalId != null
+        ? ({ actorPrincipalId } as SurfaceConversationContext["authContext"])
+        : undefined,
+    currentTurnAuthContext:
+      actorPrincipalId != null
+        ? ({
+            actorPrincipalId,
+          } as SurfaceConversationContext["currentTurnAuthContext"])
+        : undefined,
     traceEmitter: { emit: () => {} },
     sendToClient: () => {},
     pendingSurfaceActions: new Map(),
@@ -665,6 +676,31 @@ describe("surfaceProxyResolver — CU tool routing", () => {
       expect(sentMessages).toHaveLength(0);
     });
 
+    test("rejects untargeted CU dispatch to owner client when current requester is a trusted contact", async () => {
+      sentMessages.length = 0;
+      mockHasClient = true;
+      mockCuClients = [
+        {
+          clientId: "owner-cu-client",
+          capabilities: ["host_cu"],
+          actorPrincipalId: "owner-user",
+        },
+      ];
+      proxy = new HostCuProxy();
+      const ctx = buildMockContext(proxy, "owner-user", "trusted-contact-user");
+
+      const result = await surfaceProxyResolver(ctx, "computer_use_click", {
+        element_id: 1,
+        reasoning: "click",
+      });
+
+      expect(result.isError).toBe(true);
+      expect(result.content).toContain("current actor");
+      expect(proxy.stepCount).toBe(0);
+      expect(proxy.actionHistory).toHaveLength(0);
+      expect(sentMessages).toHaveLength(0);
+    });
+
     test("auto-resolves to the unique same-user CU client when cross-user clients are present", async () => {
       // Regression: previously the dispatch counted only same-user clients
       // for the multi-client guard, so 1 same-user + 1 cross-user passed the

package/src/__tests__/history-repair-hook.test.ts

@@ -40,6 +40,8 @@ const noopLogger: PluginLogger = {
 function makeCtx(messages: Message[]): UserPromptSubmitContext {
   return {
     conversationId: "conv-test",
+    userMessageId: "msg-test",
+    requestId: "req-test",
     prompt: "",
     originalMessages: messages,
     latestMessages: messages,

package/src/__tests__/llm-resolver.test.ts

@@ -1249,3 +1249,76 @@ describe("resolveDefaultProfileKey", () => {
     expect(resolveDefaultProfileKey("mainAgent", llm)).toBe("balanced");
   });
 });
+
+describe("resolveCallSiteConfig logitBias provenance", () => {
+  const kimi = "accounts/fireworks/models/kimi-k2p6";
+
+  test("forwards logitBias from the active profile that opted in", () => {
+    const llm = LLMSchema.parse({
+      default: fullDefault,
+      profiles: {
+        "balanced-economy": {
+          provider: "fireworks",
+          model: kimi,
+          logitBias: "suppress-cjk",
+        },
+      },
+      activeProfile: "balanced-economy",
+    });
+    expect(resolveCallSiteConfig("mainAgent", llm).logitBias).toBe(
+      "suppress-cjk",
+    );
+  });
+
+  test("a higher-precedence override profile that omits logitBias clears it", () => {
+    // Active profile opts in, but a pinned (override) Kimi profile did not —
+    // the override must not inherit suppress-cjk just because it resolves to
+    // Fireworks.
+    const llm = LLMSchema.parse({
+      default: fullDefault,
+      profiles: {
+        "balanced-economy": {
+          provider: "fireworks",
+          model: kimi,
+          logitBias: "suppress-cjk",
+        },
+        "my-kimi": { provider: "fireworks", model: kimi },
+      },
+      activeProfile: "balanced-economy",
+    });
+    const resolved = resolveCallSiteConfig("mainAgent", llm, {
+      overrideProfile: "my-kimi",
+    });
+    expect(resolved.logitBias).toBeUndefined();
+  });
+
+  test("does not leak the active profile's logitBias into a call site's own profile", () => {
+    // For non-main call sites the call-site profile wins; since it didn't opt
+    // in, the active profile's preset must not bleed through.
+    const llm = LLMSchema.parse({
+      default: fullDefault,
+      profiles: {
+        "balanced-economy": {
+          provider: "fireworks",
+          model: kimi,
+          logitBias: "suppress-cjk",
+        },
+        plain: { provider: "anthropic", model: "claude-opus-4-7" },
+      },
+      activeProfile: "balanced-economy",
+      callSites: { memoryExtraction: { profile: "plain" } },
+    });
+    expect(
+      resolveCallSiteConfig("memoryExtraction", llm).logitBias,
+    ).toBeUndefined();
+  });
+
+  test("a logitBias on a non-profile layer (llm.default) does not apply when the winning profile omits it", () => {
+    const llm = LLMSchema.parse({
+      default: { ...fullDefault, logitBias: "suppress-cjk" },
+      profiles: { plain: { provider: "anthropic", model: "claude-opus-4-7" } },
+      activeProfile: "plain",
+    });
+    expect(resolveCallSiteConfig("mainAgent", llm).logitBias).toBeUndefined();
+  });
+});

package/src/__tests__/memory-retrieval-hook.test.ts

@@ -36,6 +36,7 @@ const applyRuntimeInjectionsMock = mock(async (messages: unknown) => ({
 }));
 mock.module("../daemon/conversation-runtime-assembly.js", () => ({
   applyRuntimeInjections: applyRuntimeInjectionsMock,
+  resolveTurnInboundActorContext: () => null,
 }));
 
 // The hook self-resolves the live conversation and its trust class; both are
@@ -146,10 +147,8 @@ function makeHookCtx(
     } as unknown as MemoryRetrievalHookContext["logger"],
     latestMessages: [],
     requestId: "req-test",
-    mode: "full",
     isNonInteractive: false,
     modelProfile: null,
-    actorContext: null,
     ...overrides,
   };
 }

package/src/__tests__/persist-unsendable-image-downscale.test.ts

@@ -0,0 +1,145 @@
+/**
+ * Regression test for the durable-downscale path of the image-too-large
+ * recovery (JARVIS-1041 review follow-up).
+ *
+ * When an oversized stored image *can* be shrunk on this host (the common macOS
+ * path where `sips` is available), `persistUnsendableImageDowngrades` must write
+ * the downscaled bytes back to the DB — not leave the original in place. The
+ * latest tool-result media is intentionally kept in context, so leaving the
+ * full-size block would rehydrate and re-reject on every later turn instead of
+ * durably self-healing the conversation.
+ *
+ * `optimizeImageForTransport` needs `sips` and a decodable image to actually
+ * downscale, which is not portable to CI, so it is mocked here to simulate a
+ * successful shrink. The mock is process-global, so this case lives in its own
+ * file (the test runner isolates each file in its own process) to avoid
+ * disturbing the no-op-resize cases in persist-unsendable-image.test.ts.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// ── Module mock (must precede the import of the module under test) ────
+// Simulate a host where resizing succeeds: any oversized image is shrunk to a
+// small, distinct JPEG payload. durableImageReplacement checks the provider
+// caps before calling this, so in-limit images never reach the mock.
+const SHRUNK_DATA = "c2hydW5r"; // base64 for "shrunk"
+mock.module("../agent/image-optimize.js", () => ({
+  optimizeImageForTransport: () => ({
+    data: SHRUNK_DATA,
+    mediaType: "image/jpeg",
+  }),
+}));
+
+import { persistUnsendableImageDowngrades } from "../daemon/persist-unsendable-image.js";
+import {
+  addMessage,
+  createConversation,
+  getMessages,
+} from "../memory/conversation-crud.js";
+import { getDb } from "../memory/db-connection.js";
+import { initializeDb } from "../memory/db-init.js";
+import type { ContentBlock } from "../providers/types.js";
+
+initializeDb();
+
+function resetTables(): void {
+  const db = getDb();
+  db.run("DELETE FROM message_attachments");
+  db.run("DELETE FROM attachments");
+  db.run("DELETE FROM memory_segments");
+  db.run("DELETE FROM memory_embeddings");
+  db.run("DELETE FROM messages");
+  db.run("DELETE FROM conversations");
+}
+
+/** Minimal PNG whose IHDR declares dimensions past the 8000px provider cap. */
+function oversizedPngBase64(): string {
+  const width = 12000;
+  const height = 9000;
+  return Buffer.from(
+    Uint8Array.from([
+      0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, // PNG signature
+      0x00, 0x00, 0x00, 0x0d, // IHDR length (13)
+      0x49, 0x48, 0x44, 0x52, // "IHDR"
+      (width >>> 24) & 0xff,
+      (width >>> 16) & 0xff,
+      (width >>> 8) & 0xff,
+      width & 0xff,
+      (height >>> 24) & 0xff,
+      (height >>> 16) & 0xff,
+      (height >>> 8) & 0xff,
+      height & 0xff,
+      0x08, 0x06, 0x00, 0x00, 0x00,
+    ]),
+  ).toString("base64");
+}
+
+function toolResultWithImage(data: string): ContentBlock {
+  return {
+    type: "tool_result",
+    tool_use_id: "toolu_123",
+    content: "Screenshot captured",
+    contentBlocks: [
+      { type: "image", source: { type: "base64", media_type: "image/png", data } },
+    ],
+  };
+}
+
+function storedContent(conversationId: string): ContentBlock[][] {
+  return getMessages(conversationId).map(
+    (row) => JSON.parse(row.content) as ContentBlock[],
+  );
+}
+
+describe("persistUnsendableImageDowngrades (downscalable host)", () => {
+  beforeEach(() => {
+    resetTables();
+  });
+
+  /** JARVIS-1041: an oversized screenshot that CAN be shrunk must persist the
+   *  downscaled bytes, not the note and not the original. */
+  test("persists the downscaled image for a shrinkable tool_result screenshot", async () => {
+    // GIVEN a tool_result holding an oversized but shrinkable screenshot
+    const conv = createConversation();
+    await addMessage(
+      conv.id,
+      "user",
+      JSON.stringify([toolResultWithImage(oversizedPngBase64())]),
+      { skipIndexing: true },
+    );
+
+    // WHEN the downgrade is persisted
+    const rewritten = persistUnsendableImageDowngrades(conv.id);
+
+    // THEN the nested block stays an image, rewritten to the downscaled payload
+    expect(rewritten).toBe(1);
+    const [content] = storedContent(conv.id);
+    const toolResult = content.find((b) => b.type === "tool_result") as {
+      contentBlocks?: ContentBlock[];
+    };
+    const nested = toolResult.contentBlocks?.[0];
+    expect(nested?.type).toBe("image");
+    expect((nested as Extract<ContentBlock, { type: "image" }>).source.data).toBe(
+      SHRUNK_DATA,
+    );
+  });
+
+  /** Re-running is a no-op: the downscaled payload is within limits. */
+  test("is idempotent after a downscale rewrite", async () => {
+    // GIVEN a conversation whose oversized screenshot was already downscaled
+    const conv = createConversation();
+    await addMessage(
+      conv.id,
+      "user",
+      JSON.stringify([toolResultWithImage(oversizedPngBase64())]),
+      { skipIndexing: true },
+    );
+    expect(persistUnsendableImageDowngrades(conv.id)).toBe(1);
+
+    // WHEN the downgrade runs again
+    const secondRun = persistUnsendableImageDowngrades(conv.id);
+
+    // THEN nothing further is rewritten
+    expect(secondRun).toBe(0);
+  });
+});

package/src/__tests__/persist-unsendable-image.test.ts

@@ -14,7 +14,10 @@
 
 import { beforeEach, describe, expect, test } from "bun:test";
 
-import { persistUnsendableImageDowngrades } from "../daemon/persist-unsendable-image.js";
+import {
+  oversizedImageReplacement,
+  persistUnsendableImageDowngrades,
+} from "../daemon/persist-unsendable-image.js";
 import {
   addMessage,
   createConversation,
@@ -87,6 +90,20 @@ function imageBlock(data: string): ContentBlock {
   };
 }
 
+/**
+ * A tool_result carrying a nested image in its contentBlocks, mirroring what a
+ * browser screenshot produces. This is the JARVIS-1041 shape: the oversized
+ * image lives at tool_result.contentBlocks, never as a top-level block.
+ */
+function toolResultWithImage(data: string): ContentBlock {
+  return {
+    type: "tool_result",
+    tool_use_id: "toolu_123",
+    content: "Screenshot captured",
+    contentBlocks: [imageBlock(data)],
+  };
+}
+
 function storedContent(conversationId: string): ContentBlock[][] {
   return getMessages(conversationId).map(
     (row) => JSON.parse(row.content) as ContentBlock[],
@@ -194,6 +211,61 @@ describe("persistUnsendableImageDowngrades", () => {
     expect(content.some((b) => b.type === "image")).toBe(false);
   });
 
+  /** JARVIS-1041: the oversized image is nested inside a tool_result (e.g. a
+   *  browser screenshot), not a top-level block. The downgrade must descend
+   *  into tool_result.contentBlocks and swap the nested image for a note, while
+   *  keeping the tool_result itself intact so tool_use/tool_result pairing
+   *  survives. */
+  test("downgrades an oversized image nested in tool_result.contentBlocks", async () => {
+    // GIVEN an assistant turn whose tool_result holds an oversized screenshot
+    const conv = createConversation();
+    await addMessage(
+      conv.id,
+      "user",
+      JSON.stringify([toolResultWithImage(makePngBase64(12000, 9000))]),
+      { skipIndexing: true },
+    );
+
+    // WHEN the downgrade is persisted
+    const rewritten = persistUnsendableImageDowngrades(conv.id);
+
+    // THEN the message is rewritten with the nested image swapped for a note
+    expect(rewritten).toBe(1);
+    const [content] = storedContent(conv.id);
+    const toolResult = content.find((b) => b.type === "tool_result");
+    expect(toolResult).toBeDefined();
+    // AND the tool_result is preserved (pairing intact) with no image left
+    const nested = (toolResult as { contentBlocks?: ContentBlock[] })
+      .contentBlocks;
+    expect(nested?.some((b) => b.type === "image")).toBe(false);
+    expect(nested?.some((b) => b.type === "text")).toBe(true);
+  });
+
+  /** A sendable nested screenshot is never disturbed. */
+  test("leaves a normally-sized tool_result image untouched", async () => {
+    // GIVEN a tool_result with an image well within provider limits
+    const conv = createConversation();
+    await addMessage(
+      conv.id,
+      "user",
+      JSON.stringify([toolResultWithImage(makePngBase64(1024, 768))]),
+      { skipIndexing: true },
+    );
+
+    // WHEN the downgrade is persisted
+    const rewritten = persistUnsendableImageDowngrades(conv.id);
+
+    // THEN nothing is rewritten and the nested image remains
+    expect(rewritten).toBe(0);
+    const [content] = storedContent(conv.id);
+    const toolResult = content.find((b) => b.type === "tool_result") as {
+      contentBlocks?: ContentBlock[];
+    };
+    expect(toolResult.contentBlocks?.some((b) => b.type === "image")).toBe(
+      true,
+    );
+  });
+
   /** Re-running after a rewrite is a safe no-op (no image blocks remain). */
   test("is idempotent — a second run rewrites nothing", async () => {
     // GIVEN a conversation whose oversized image has already been downgraded
@@ -213,3 +285,27 @@ describe("persistUnsendableImageDowngrades", () => {
     expect(secondRun).toBe(0);
   });
 });
+
+describe("oversizedImageReplacement", () => {
+  /** A still-sendable image must be left alone — never replaced with a note.
+   *  This is the gate that keeps the in-memory recovery from discarding valid
+   *  screenshots when only one image in the turn was actually oversized. */
+  test("returns null for an image within the provider caps", () => {
+    const sendable = imageBlock(makePngBase64(1024, 768)) as Extract<
+      ContentBlock,
+      { type: "image" }
+    >;
+    expect(oversizedImageReplacement(sendable)).toBeNull();
+  });
+
+  /** An image past the provider caps that cannot be shrunk on this host (fake
+   *  PNG that sips cannot decode) collapses to the unsendable note. */
+  test("returns the unsendable note when an oversized image cannot be shrunk", () => {
+    const oversized = imageBlock(makePngBase64(12000, 9000)) as Extract<
+      ContentBlock,
+      { type: "image" }
+    >;
+    const replacement = oversizedImageReplacement(oversized);
+    expect(replacement?.type).toBe("text");
+  });
+});

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

@@ -0,0 +1,68 @@
+/**
+ * Tests for the `globalThis.__vellumPluginRuntime` bridge.
+ *
+ * The bridge exists so workspace-local plugins (`<workspaceDir>/plugins/*`)
+ * can register with the daemon's bundled module instances even when the
+ * daemon is a `bun --compile` binary. Absolute-path imports against a
+ * compiled binary load fresh disk copies into a disjoint module graph; the
+ * bridge sidesteps that by attaching a stable handle to globalThis.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import {
+  getPluginRuntime,
+  installPluginRuntime,
+  uninstallPluginRuntimeForTests,
+} from "../plugins/external-api.js";
+import { registerPlugin } from "../plugins/registry.js";
+import { assistantEventHub } from "../runtime/assistant-event-hub.js";
+import { getSecureKeyAsync } from "../security/secure-keys.js";
+
+describe("plugin external-api bridge", () => {
+  beforeEach(() => {
+    uninstallPluginRuntimeForTests();
+  });
+
+  afterEach(() => {
+    uninstallPluginRuntimeForTests();
+  });
+
+  test("installs a runtime handle on globalThis", () => {
+    expect(getPluginRuntime()).toBeUndefined();
+    installPluginRuntime();
+    const runtime = getPluginRuntime();
+    expect(runtime).toBeDefined();
+    expect(runtime?.version).toBe(1);
+  });
+
+  test("exposes the canonical registerPlugin / hub / secrets references", () => {
+    installPluginRuntime();
+    const runtime = getPluginRuntime();
+    expect(runtime?.registerPlugin).toBe(registerPlugin);
+    expect(runtime?.assistantEventHub).toBe(assistantEventHub);
+    expect(runtime?.getSecureKeyAsync).toBe(getSecureKeyAsync);
+  });
+
+  test("plugins can read the runtime via the documented globalThis key", () => {
+    installPluginRuntime();
+    // Mirror the access pattern documented for plugin authors.
+    const runtime = (
+      globalThis as { __vellumPluginRuntime?: { version: number } }
+    ).__vellumPluginRuntime;
+    expect(runtime).toBeDefined();
+    expect(runtime?.version).toBe(1);
+  });
+
+  test("install is idempotent — repeat calls preserve the same handle", () => {
+    installPluginRuntime();
+    const first = getPluginRuntime();
+    installPluginRuntime();
+    installPluginRuntime();
+    expect(getPluginRuntime()).toBe(first);
+  });
+
+  test("getPluginRuntime returns undefined when the bridge is not installed", () => {
+    expect(getPluginRuntime()).toBeUndefined();
+  });
+});