@vellumai/assistant 0.8.0 → 0.8.2

package/src/__tests__/plugin-bootstrap.test.ts

@@ -43,7 +43,6 @@ import {
 import { runShutdownHooks } from "../daemon/shutdown-registry.js";
 import { RiskLevel } from "../permissions/types.js";
 import {
-  ASSISTANT_API_VERSIONS,
   getInjectors,
   getMiddlewaresFor,
   registerPlugin,
@@ -70,26 +69,53 @@ const fakeCtx: DaemonContext = {
   assistantVersion: "9.9.9-test",
 };
 
+/**
+ * Test helper. Accepts the new `hooks` bag and ALSO legacy top-level
+ * `init` / `onShutdown` for ergonomics — the helper merges them into a
+ * single `hooks` field that matches the runtime Plugin shape. This keeps
+ * the test call sites compact without leaking the old contract.
+ */
 function buildPlugin(
   name: string,
-  extras: Partial<Omit<Plugin, "manifest">> = {},
+  extras: Partial<Omit<Plugin, "manifest" | "hooks">> & {
+    hooks?: Plugin["hooks"];
+    init?: (ctx: PluginInitContext) => Promise<void>;
+    onShutdown?: () => Promise<void>;
+  } = {},
   options: {
-    requires?: Record<string, string>;
     requiresCredential?: string[];
     requiresFlag?: string[];
   } = {},
 ): Plugin {
+  const {
+    init: legacyInit,
+    onShutdown: legacyOnShutdown,
+    hooks: explicitHooks,
+    ...rest
+  } = extras;
+  const mergedHooks: Plugin["hooks"] | undefined =
+    legacyInit !== undefined ||
+    legacyOnShutdown !== undefined ||
+    explicitHooks !== undefined
+      ? {
+          ...(explicitHooks ?? {}),
+          ...(legacyInit !== undefined ? { init: legacyInit } : {}),
+          ...(legacyOnShutdown !== undefined
+            ? { shutdown: legacyOnShutdown }
+            : {}),
+        }
+      : undefined;
   return {
     manifest: {
       name,
       version: "0.0.1",
-      requires: options.requires ?? { pluginRuntime: "v1" },
       ...(options.requiresCredential
         ? { requiresCredential: options.requiresCredential }
         : {}),
       ...(options.requiresFlag ? { requiresFlag: options.requiresFlag } : {}),
     },
-    ...extras,
+    ...rest,
+    ...(mergedHooks ? { hooks: mergedHooks } : {}),
   };
 }
 
@@ -132,10 +158,6 @@ describe("plugin bootstrap", () => {
     );
     expect(existsSync(ctx.pluginStorageDir)).toBe(true);
     expect(ctx.assistantVersion).toBe("9.9.9-test");
-    // apiVersions must surface the canonical capability table from the
-    // registry so plugins can negotiate at runtime.
-    expect(ctx.apiVersions).toBe(ASSISTANT_API_VERSIONS);
-    expect(ctx.apiVersions.pluginRuntime).toEqual(["v1"]);
   });
 
   test("credential resolution: init receives the resolved value under credentials[key]", async () => {
@@ -186,29 +208,15 @@ describe("plugin bootstrap", () => {
     expect(msg).toContain("absent-key");
   });
 
-  test("version mismatch: registration surfaces a clear error naming the plugin", () => {
-    // The assistant only exposes pluginRuntime@v1 — asking for v99 must fail
-    // registration with the plugin name in the message. The error is raised
-    // at registerPlugin() rather than bootstrap, because the registry is the
-    // single authoritative point of capability validation.
-    const plugin = buildPlugin(
-      "from-the-future",
-      {},
-      { requires: { pluginRuntime: "v99" } },
-    );
-
-    let caught: unknown;
-    try {
-      registerPlugin(plugin);
-    } catch (err) {
-      caught = err;
-    }
-    expect(caught).toBeInstanceOf(PluginExecutionError);
-    const msg = (caught as PluginExecutionError).message;
-    expect(msg).toContain("from-the-future");
-    expect(msg).toContain("pluginRuntime");
-    expect(msg).toContain("v99");
-    expect((caught as PluginExecutionError).pluginName).toBe("from-the-future");
+  test("version mismatch: external plugin loader rejects when peerDependency unsatisfied", async () => {
+    // Host-compat negotiation lives in the external-plugin loader against
+    // `peerDependencies["@vellumai/plugin-api"]`. The registry no longer
+    // re-validates a manifest-level `requires` block — the loader is the
+    // single authoritative point. End-to-end coverage of the loader path
+    // lives in `external-plugin-loader.test.ts`; this test asserts the
+    // bootstrap doesn't gain its own validation surface.
+    const plugin = buildPlugin("compat-claim-checked-upstream");
+    expect(() => registerPlugin(plugin)).not.toThrow();
   });
 
   test("plugin init throw: bootstrap throws a PluginExecutionError naming the plugin", async () => {
@@ -366,13 +374,8 @@ describe("plugin bootstrap", () => {
           {
             name: "gated-off-tool",
             description: "should not be registered",
-            category: "plugin-test",
             defaultRiskLevel: RiskLevel.Low,
-            getDefinition: () => ({
-              name: "gated-off-tool",
-              description: "should not be registered",
-              input_schema: { type: "object", properties: {}, required: [] },
-            }),
+            input_schema: { type: "object", properties: {}, required: [] },
             execute: async () => ({ content: "nope", isError: false }),
           },
         ],

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();
+  });
+});

package/src/__tests__/plugin-registry.test.ts

@@ -9,7 +9,6 @@
 import { beforeEach, describe, expect, test } from "bun:test";
 
 import {
-  ASSISTANT_API_VERSIONS,
   closeRegistration,
   getInjectors,
   getMiddlewaresFor,
@@ -30,13 +29,11 @@ import {
 function buildPlugin(
   name: string,
   extras: Partial<Omit<Plugin, "manifest">> = {},
-  requiresOverride?: Record<string, string>,
 ): Plugin {
   return {
     manifest: {
       name,
       version: "0.0.1",
-      requires: requiresOverride ?? { pluginRuntime: "v1" },
     },
     ...extras,
   };
@@ -106,7 +103,6 @@ describe("plugin registry", () => {
     const bad = {
       manifest: {
         version: "0.0.1",
-        requires: { pluginRuntime: "v1" },
       },
     } as unknown as Plugin;
     expect(() => registerPlugin(bad)).toThrow(/manifest\.name is required/);
@@ -148,84 +144,11 @@ describe("plugin registry", () => {
     const bad = {
       manifest: {
         name: "missing-version",
-        requires: { pluginRuntime: "v1" },
       },
     } as unknown as Plugin;
     expect(() => registerPlugin(bad)).toThrow(/manifest\.version is required/);
   });
 
-  test("throws when manifest.requires is missing", () => {
-    const bad = {
-      manifest: { name: "missing-requires", version: "0.0.1" },
-    } as unknown as Plugin;
-    expect(() => registerPlugin(bad)).toThrow(/manifest\.requires is required/);
-  });
-
-  test("throws when requires.pluginRuntime is missing", () => {
-    const plugin = buildPlugin(
-      "no-runtime",
-      {},
-      // Valid shape but no pluginRuntime entry.
-      { memoryApi: "v1" },
-    );
-    expect(() => registerPlugin(plugin)).toThrow(PluginExecutionError);
-    expect(() => registerPlugin(plugin)).toThrow(/pluginRuntime/);
-  });
-
-  test("throws with version-mismatch message when a required version is not exposed", () => {
-    // The assistant seeds memoryApi with ["v1"]. Requesting v2 must fail.
-    const plugin = buildPlugin(
-      "too-new",
-      {},
-      {
-        pluginRuntime: "v1",
-        memoryApi: "v2",
-      },
-    );
-
-    expect(() => registerPlugin(plugin)).toThrow(PluginExecutionError);
-
-    // Sanity-check the assistant actually exposes only v1 for memoryApi so
-    // this test fails loudly if the capability table ever adds v2.
-    expect(ASSISTANT_API_VERSIONS.memoryApi).toEqual(["v1"]);
-
-    try {
-      registerPlugin(plugin);
-      throw new Error("expected registerPlugin to throw");
-    } catch (err) {
-      expect(err).toBeInstanceOf(PluginExecutionError);
-      const msg = (err as PluginExecutionError).message;
-      // Error message must reference plugin name, API, required version,
-      // and the versions the assistant exposes.
-      expect(msg).toContain("too-new");
-      expect(msg).toContain("memoryApi");
-      expect(msg).toContain("v2");
-      expect(msg).toContain("v1");
-      expect((err as PluginExecutionError).pluginName).toBe("too-new");
-    }
-  });
-
-  test("throws with clear message when a required capability is unknown", () => {
-    const plugin = buildPlugin(
-      "asks-for-mystery",
-      {},
-      {
-        pluginRuntime: "v1",
-        thisDoesNotExist: "v1",
-      },
-    );
-    expect(() => registerPlugin(plugin)).toThrow(PluginExecutionError);
-    try {
-      registerPlugin(plugin);
-      throw new Error("expected registerPlugin to throw");
-    } catch (err) {
-      const msg = (err as PluginExecutionError).message;
-      expect(msg).toContain("asks-for-mystery");
-      expect(msg).toContain("thisDoesNotExist");
-      expect(msg).toContain("(none)");
-    }
-  });
-
   test("getInjectors returns injectors sorted by order ascending", () => {
     const high: Injector = {
       name: "high-order",

package/src/__tests__/plugin-route-contribution.test.ts

@@ -53,7 +53,7 @@ import {
   registerPlugin,
   resetPluginRegistryForTests,
 } from "../plugins/registry.js";
-import type { Plugin } from "../plugins/types.js";
+import type { Plugin, PluginInitContext } from "../plugins/types.js";
 import {
   matchSkillRoute,
   resetSkillRoutesForTests,
@@ -76,17 +76,44 @@ const fakeCtx: DaemonContext = {
 };
 
 /** Build a minimal valid plugin with optional route contributions. */
+/**
+ * Test helper. Accepts the new `hooks` bag and ALSO legacy top-level
+ * `init` / `onShutdown` for ergonomics — the helper merges them into a
+ * single `hooks` field that matches the runtime Plugin shape.
+ */
 function buildPlugin(
   name: string,
-  extras: Partial<Omit<Plugin, "manifest">> = {},
+  extras: Partial<Omit<Plugin, "manifest" | "hooks">> & {
+    hooks?: Plugin["hooks"];
+    init?: (ctx: PluginInitContext) => Promise<void>;
+    onShutdown?: () => Promise<void>;
+  } = {},
 ): Plugin {
+  const {
+    init: legacyInit,
+    onShutdown: legacyOnShutdown,
+    hooks: explicitHooks,
+    ...rest
+  } = extras;
+  const mergedHooks: Plugin["hooks"] | undefined =
+    legacyInit !== undefined ||
+    legacyOnShutdown !== undefined ||
+    explicitHooks !== undefined
+      ? {
+          ...(explicitHooks ?? {}),
+          ...(legacyInit !== undefined ? { init: legacyInit } : {}),
+          ...(legacyOnShutdown !== undefined
+            ? { shutdown: legacyOnShutdown }
+            : {}),
+        }
+      : undefined;
   return {
     manifest: {
       name,
       version: "0.0.1",
-      requires: { pluginRuntime: "v1" },
     },
-    ...extras,
+    ...rest,
+    ...(mergedHooks ? { hooks: mergedHooks } : {}),
   };
 }
 

package/src/__tests__/plugin-skill-contribution.test.ts

@@ -80,7 +80,6 @@ function buildSkillPlugin(
     manifest: {
       name,
       version: "0.0.1",
-      requires: { pluginRuntime: "v1" },
     },
     skills,
     ...extras,
@@ -204,7 +203,6 @@ describe("plugin skill contributions", () => {
       manifest: {
         name: "no-skills-plugin",
         version: "0.0.1",
-        requires: { pluginRuntime: "v1" },
       },
     });
 

package/src/__tests__/plugin-tool-contribution.test.ts

@@ -48,8 +48,7 @@ import {
   registerPlugin,
   resetPluginRegistryForTests,
 } from "../plugins/registry.js";
-import type { Plugin } from "../plugins/types.js";
-import type { ToolDefinition } from "../providers/types.js";
+import type { Plugin, PluginInitContext } from "../plugins/types.js";
 import {
   __clearRegistryForTesting,
   __resetRegistryForTesting,
@@ -59,7 +58,11 @@ import {
   registerPluginTools,
   unregisterPluginTools,
 } from "../tools/registry.js";
-import type { Tool, ToolContext, ToolExecutionResult } from "../tools/types.js";
+import type {
+  PluginTool,
+  ToolContext,
+  ToolExecutionResult,
+} from "../tools/types.js";
 
 // Redirect plugin-storage-directory creation into a per-process temp tree so
 // the test doesn't touch the developer's real ~/.vellum. This matches the
@@ -76,19 +79,15 @@ const fakeCtx: DaemonContext = {
   assistantVersion: "9.9.9-test",
 };
 
-function makeFakeTool(name: string, extras: Partial<Tool> = {}): Tool {
+function makeFakeTool(
+  name: string,
+  extras: Partial<PluginTool> = {},
+): PluginTool {
   return {
     name,
     description: `Fake ${name}`,
-    category: "plugin-test",
     defaultRiskLevel: RiskLevel.Low,
-    getDefinition(): ToolDefinition {
-      return {
-        name,
-        description: `Fake ${name}`,
-        input_schema: { type: "object", properties: {}, required: [] },
-      };
-    },
+    input_schema: { type: "object", properties: {}, required: [] },
     async execute(
       _input: Record<string, unknown>,
       _context: ToolContext,
@@ -99,17 +98,44 @@ function makeFakeTool(name: string, extras: Partial<Tool> = {}): Tool {
   };
 }
 
+/**
+ * Test helper. Accepts the new `hooks` bag and ALSO legacy top-level
+ * `init` / `onShutdown` for ergonomics — the helper merges them into a
+ * single `hooks` field that matches the runtime Plugin shape.
+ */
 function buildPlugin(
   name: string,
-  extras: Partial<Omit<Plugin, "manifest">> = {},
+  extras: Partial<Omit<Plugin, "manifest" | "hooks">> & {
+    hooks?: Plugin["hooks"];
+    init?: (ctx: PluginInitContext) => Promise<void>;
+    onShutdown?: () => Promise<void>;
+  } = {},
 ): Plugin {
+  const {
+    init: legacyInit,
+    onShutdown: legacyOnShutdown,
+    hooks: explicitHooks,
+    ...rest
+  } = extras;
+  const mergedHooks: Plugin["hooks"] | undefined =
+    legacyInit !== undefined ||
+    legacyOnShutdown !== undefined ||
+    explicitHooks !== undefined
+      ? {
+          ...(explicitHooks ?? {}),
+          ...(legacyInit !== undefined ? { init: legacyInit } : {}),
+          ...(legacyOnShutdown !== undefined
+            ? { shutdown: legacyOnShutdown }
+            : {}),
+        }
+      : undefined;
   return {
     manifest: {
       name,
       version: "0.0.1",
-      requires: { pluginRuntime: "v1" },
     },
-    ...extras,
+    ...rest,
+    ...(mergedHooks ? { hooks: mergedHooks } : {}),
   };
 }
 
@@ -221,17 +247,20 @@ describe("registerPluginTools / unregisterPluginTools helpers", () => {
     __resetRegistryForTesting();
   });
 
-  test("registerPluginTools stamps origin and ownerPluginId from the plugin name", () => {
-    // Even if the plugin author hands in a tool with no ownership metadata,
-    // the helper fills it in so the tool can be unregistered later.
+  test("registerPluginTools stamps category, origin, and ownerPluginId from the plugin name", () => {
+    // Even if the plugin author hands in a tool with no category or ownership
+    // metadata, the helper fills it in so the tool can be registered and
+    // unregistered consistently.
     const accepted = registerPluginTools("my-plugin", [
       makeFakeTool("pt_stamped"),
     ]);
     expect(accepted).toHaveLength(1);
+    expect(accepted[0]?.category).toBe("plugin");
     expect(accepted[0]?.origin).toBe("plugin");
     expect(accepted[0]?.ownerPluginId).toBe("my-plugin");
 
     const retrieved = getTool("pt_stamped");
+    expect(retrieved?.category).toBe("plugin");
     expect(retrieved?.origin).toBe("plugin");
     expect(retrieved?.ownerPluginId).toBe("my-plugin");
   });

package/src/__tests__/plugin-types.test.ts

@@ -46,7 +46,7 @@ import {
   type ToolResultTruncateResult,
   type TurnContext,
 } from "../plugins/types.js";
-import type { Tool } from "../tools/types.js";
+import type { PluginTool } from "../tools/types.js";
 
 const sampleTrust: TrustContext = {
   sourceChannel: "vellum",
@@ -66,8 +66,6 @@ describe("plugin core types", () => {
     const manifest: PluginManifest = {
       name: "sample-plugin",
       version: "0.1.0",
-      provides: { sampleApi: "v1" },
-      requires: { pluginRuntime: "v1" },
       requiresCredential: ["SAMPLE_API_KEY"],
       requiresFlag: ["sample-feature"],
       config: { parse: (input: unknown) => input },
@@ -209,18 +207,11 @@ describe("plugin core types", () => {
       },
     };
 
-    const sampleTool: Tool = {
+    const sampleTool: PluginTool = {
       name: "sample-tool",
       description: "Sample plugin tool",
-      category: "plugins",
       defaultRiskLevel: RiskLevel.Low,
-      getDefinition() {
-        return {
-          name: "sample-tool",
-          description: "Sample plugin tool",
-          input_schema: { type: "object", properties: {}, required: [] },
-        };
-      },
+      input_schema: { type: "object", properties: {}, required: [] },
       async execute() {
         return { content: "ok", isError: false };
       },
@@ -228,17 +219,18 @@ describe("plugin core types", () => {
 
     const plugin = {
       manifest,
-      async init(ctx: PluginInitContext) {
-        // Touch every field so refactors that rename any of them break here.
-        void ctx.config;
-        void ctx.credentials;
-        void ctx.logger;
-        void ctx.pluginStorageDir;
-        void ctx.assistantVersion;
-        void ctx.apiVersions;
-      },
-      async onShutdown() {
-        // no-op
+      hooks: {
+        async init(ctx: PluginInitContext) {
+          // Touch every field so refactors that rename any of them break here.
+          void ctx.config;
+          void ctx.credentials;
+          void ctx.logger;
+          void ctx.pluginStorageDir;
+          void ctx.assistantVersion;
+        },
+        async shutdown() {
+          // no-op
+        },
       },
       tools: [sampleTool],
       routes: [

package/src/__tests__/process-message-background-slack.test.ts

@@ -30,6 +30,14 @@ mock.module("../memory/conversation-disk-view.js", () => ({
   updateMetaFile: () => {},
 }));
 
+const broadcastMessages: unknown[] = [];
+
+mock.module("../runtime/assistant-event-hub.js", () => ({
+  broadcastMessage: (msg: unknown) => {
+    broadcastMessages.push(msg);
+  },
+}));
+
 mock.module("../runtime/confirmation-request-guardian-bridge.js", () => ({
   bridgeConfirmationRequestToGuardian: () => {},
 }));
@@ -137,6 +145,7 @@ import type {
   TurnChannelContext,
   TurnInterfaceContext,
 } from "../channels/types.js";
+import { conversationMessagesSyncTag } from "../daemon/message-types/sync.js";
 import {
   processMessage,
   processMessageInBackground,
@@ -240,6 +249,7 @@ describe("processMessageInBackground Slack option propagation", () => {
   beforeEach(() => {
     activeConversation = makeConversation();
     mergeConversationOptionsMock.mockClear();
+    broadcastMessages.length = 0;
   });
 
   test("passes Slack inbound metadata to persistence and exposes the runtime notice during the loop", async () => {
@@ -309,6 +319,49 @@ describe("processMessageInBackground Slack option propagation", () => {
     expect(activeConversation.__clientSenders).toHaveLength(2);
   });
 
+  test("observes live agent events without replacing the broadcast emitter", async () => {
+    const observedMessages: unknown[] = [];
+
+    const processing = processMessage(
+      "conv-background-slack",
+      "Reply from Slack",
+      undefined,
+      {
+        onEvent: (msg) => {
+          observedMessages.push(msg);
+        },
+      },
+      "slack",
+      "slack",
+    );
+
+    await waitForRunAgentLoopCall();
+
+    const loopOnEvent = activeConversation.runAgentLoop.mock.calls[0][2] as
+      | ((msg: unknown) => void)
+      | undefined;
+    const delta = {
+      type: "assistant_text_delta",
+      text: "Working on it.",
+      conversationId: "conv-background-slack",
+    };
+    loopOnEvent?.(delta);
+
+    expect(broadcastMessages).toEqual([
+      {
+        type: "sync_changed",
+        tags: [conversationMessagesSyncTag("conv-background-slack")],
+      },
+      delta,
+    ]);
+    expect(observedMessages).toEqual([delta]);
+
+    activeConversation.__loopDeferred.resolve();
+    await expect(processing).resolves.toEqual({
+      messageId: "persisted-user-message-id",
+    });
+  });
+
   test("leaves non-Slack background persistence metadata absent", async () => {
     await processMessageInBackground(
       "conv-background-slack",