@vellumai/assistant 0.8.1 → 0.8.2

package/examples/plugins/echo/README.md

@@ -30,49 +30,49 @@ For the full plugin authoring guide, see
 
 ## Install locally
 
-The assistant scans `~/.vellum/plugins/*` for subdirectories containing a
+The assistant scans `<workspaceDir>/plugins/*` (e.g.
+`~/.vellum/workspace/plugins/`) for subdirectories containing a
 `register.{ts,js}` file and dynamic-imports each one during assistant
 startup. Dropping (or symlinking) this directory in place is enough to
 enable it.
 
-### Option 1 — symlink from the repo (recommended)
+The plugin reads `registerPlugin` from `globalThis.__vellumPluginRuntime`,
+which the daemon attaches before scanning plugins. This works against both
+the `bun --compile`-bundled daemon binary AND a daemon running from
+source — no special install procedure required either way.
+
+### Option 1 — symlink from the repo (simplest in-repo dev)
 
 From the repo root:
 
 ```bash
-mkdir -p ~/.vellum/plugins
-ln -s "$(pwd)/assistant/examples/plugins/echo" ~/.vellum/plugins/echo
+mkdir -p ~/.vellum/workspace/plugins
+ln -s "$(pwd)/assistant/examples/plugins/echo" ~/.vellum/workspace/plugins/echo
 ```
 
 Symlinks let you edit the plugin in-place and restart the assistant to
-pick up changes. **This is the only zero-edit install path** — the
-`register.ts` in this directory uses relative imports
-(`../../../src/plugins/registry.js`) that resolve into the in-repo
-assistant sources, so the file must stay reachable at that relative
-location.
-
-### Option 2 — standalone copy (requires edits)
-
-If you want a fully isolated install that does not depend on a local
-vellum-assistant checkout, a plain `cp -R` of this directory into
-`~/.vellum/plugins/echo/` will **not** work as-is: the relative imports
-in `register.ts` resolve to `~/.vellum/src/plugins/...`, which does not
-exist. The assistant does not currently publish the plugin API as an npm
-package, so to copy-and-adapt this template into a standalone plugin you
-must rewrite the imports in `register.ts` to point at an absolute path
-inside a vellum-assistant checkout, for example:
+pick up changes.
+
+### Option 2 — standalone copy
+
+A plain `cp -R` of this directory into `~/.vellum/workspace/plugins/echo/`
+works for the runtime imports (which go through the global bridge), but
+the `import type` lines at the top of `register.ts` still resolve into
+the in-repo assistant source tree. If your standalone copy lives outside
+a vellum-assistant checkout, rewrite those `import type` paths to point
+at an absolute path inside any checkout — they're erased at compile time
+and have no module-identity effect at runtime:
 
 ```ts
 // before (repo-local):
-import { registerPlugin } from "../../../src/plugins/registry.js";
+import type { VellumPluginRuntime } from "../../../src/plugins/external-api.js";
+import type { Plugin } from "../../../src/plugins/types.js";
 // after (standalone, edit to your checkout path):
-import { registerPlugin } from "/path/to/vellum-assistant/assistant/src/plugins/registry.js";
+import type { VellumPluginRuntime } from "/path/to/vellum-assistant/assistant/src/plugins/external-api.js";
+import type { Plugin } from "/path/to/vellum-assistant/assistant/src/plugins/types.js";
 ```
 
-Apply the same rewrite to the `import type` line that pulls from
-`../../../src/plugins/types.js`. Until a published package exists, the
-symlink recipe above is simpler and more portable for day-to-day
-development.
+No runtime-import rewriting is needed — the bridge already handles that.
 
 ### Restart the assistant
 
@@ -113,7 +113,7 @@ original error still propagates.
 Remove the symlink (or the copied directory) and restart the assistant:
 
 ```bash
-rm ~/.vellum/plugins/echo
+rm ~/.vellum/workspace/plugins/echo
 vellum restart
 ```
 

package/examples/plugins/echo/package.json

@@ -9,6 +9,9 @@
   "engines": {
     "node": ">=20.12.0"
   },
+  "peerDependencies": {
+    "@vellumai/plugin-api": "^0.8.0"
+  },
   "devDependencies": {
     "@types/bun": "1.3.10",
     "@types/node": "25.5.0",

package/examples/plugins/echo/register.ts

@@ -2,34 +2,26 @@
  * Echo plugin — observes every assistant pipeline and logs one structured
  * line per invocation to stderr.
  *
- * This plugin is bundled in the repository as an authoring reference. It is
- * not shipped with the assistant runtime; to try it locally, symlink this
- * directory into `~/.vellum/plugins/echo/` and restart the assistant. See
- * `README.md` in this directory for the full install recipe and
- * `assistant/docs/plugins.md` for general plugin authoring docs.
+ * Bundled in the repository as an authoring reference. To try it locally,
+ * symlink (or copy) this directory into `<workspaceDir>/plugins/echo/` and
+ * restart the assistant. See `README.md` in this directory for the install
+ * recipe and `assistant/docs/plugins.md` for general plugin authoring docs.
  *
- * ## IMPORTANT — imports below are REPO-LOCAL
+ * ## Runtime bridge
  *
- * The relative imports from `../../../src/plugins/...` resolve correctly
- * only while this file lives inside the vellum-assistant repo at
- * `assistant/examples/plugins/echo/`. The path walks back to
- * `assistant/src/plugins/` so the example compiles against the assistant's
- * in-repo types.
+ * The plugin reads `registerPlugin` from `globalThis.__vellumPluginRuntime`,
+ * a stable handle the daemon attaches at startup. This lets the same plugin
+ * file work whether the daemon is running from source (relative or absolute
+ * imports would resolve to the daemon's modules) or as a `bun --compile`
+ * binary (where absolute imports would load a disjoint disk copy with a
+ * separate registry instance). The bridge is documented in
+ * `assistant/src/plugins/external-api.ts`.
  *
- * If you copy (rather than symlink) this directory to
- * `~/.vellum/plugins/echo/`, these imports will fail because
- * `~/.vellum/src/plugins/...` does not exist. The assistant does not
- * currently publish the plugin API as an npm package, so the only
- * zero-edit install path is the symlink recipe (Option 1 in README.md).
- *
- * For a standalone copy that lives outside the repo, you must either:
- * - Point the imports at an absolute path into a vellum-assistant checkout
- *   (`/path/to/vellum-assistant/assistant/src/plugins/registry.js`), or
- * - Rewrite the plugin to consume only the public types you need and drop
- *   the direct registry import in favor of your own entry-point wiring.
- *
- * See README.md "Option 2 — standalone copy" for the recommended
- * standalone-template adaptation steps.
+ * Type imports below still come from the in-repo source tree. Types are
+ * erased at runtime, so they don't affect module identity — but they only
+ * resolve while this file lives inside the vellum-assistant checkout. For a
+ * standalone-copy install, rewrite the `import type` paths to absolute paths
+ * inside a checkout (or vendor only the types you need).
  *
  * ## Design
  *
@@ -48,7 +40,7 @@
  * user-plugin-loader contract (see `assistant/src/plugins/user-loader.ts`).
  */
 
-import { registerPlugin } from "../../../src/plugins/registry.js";
+import type { VellumPluginRuntime } from "../../../src/plugins/external-api.js";
 import type {
   CircuitBreakerArgs,
   CircuitBreakerResult,
@@ -81,6 +73,15 @@ import type {
   TurnResult,
 } from "../../../src/plugins/types.js";
 
+const runtime = (globalThis as { __vellumPluginRuntime?: VellumPluginRuntime })
+  .__vellumPluginRuntime;
+if (!runtime || runtime.version !== 1) {
+  throw new Error(
+    "echo plugin: globalThis.__vellumPluginRuntime is missing or has an unexpected version — install a recent assistant build",
+  );
+}
+const { registerPlugin } = runtime;
+
 const PLUGIN_NAME = "echo";
 
 /**
@@ -136,9 +137,10 @@ function makeObserver<A, R>(
  * `PipelineMiddlewareMap` — all thin observers produced by `makeObserver`.
  *
  * Manifest:
- * - `requires.pluginRuntime: "v1"` satisfies the registry's mandatory
- *   capability negotiation.
- * - `provides: {}` — the plugin exposes no capabilities to other plugins.
+ * - Host-compat range lives in `package.json` under
+ *   `peerDependencies["@vellumai/plugin-api"]`. The external-plugin loader
+ *   validates it against the running assistant version via
+ *   `semver.satisfies()` before this file is even imported.
  * - No `requiresCredential` or `requiresFlag` — the plugin needs no external
  *   state and runs unconditionally.
  */
@@ -146,8 +148,6 @@ const echoPlugin: Plugin = {
   manifest: {
     name: PLUGIN_NAME,
     version: "0.1.0",
-    provides: {},
-    requires: { pluginRuntime: "v1" },
   },
   middleware: {
     turn: makeObserver<TurnArgs, TurnResult>("turn"),

package/node_modules/@vellumai/slack-text/src/index.test.ts

@@ -1,7 +1,9 @@
 import { describe, expect, test } from "bun:test";
 
 import {
+  buildSlackChannelLabelMap,
   buildSlackUserLabelMap,
+  extractSlackChannelReferenceIds,
   extractSlackUserMentionIds,
   renderSlackTextForModel,
 } from "./index.js";
@@ -9,17 +11,27 @@ import {
 describe("extractSlackUserMentionIds", () => {
   test("returns unique user mention IDs in encounter order", () => {
     expect(
-      extractSlackUserMentionIds("<@U123> hi <@W456> and <@U123> again")
+      extractSlackUserMentionIds("<@U123> hi <@W456> and <@U123> again"),
     ).toEqual(["U123", "W456"]);
   });
 });
 
+describe("extractSlackChannelReferenceIds", () => {
+  test("returns unique channel reference IDs in encounter order", () => {
+    expect(
+      extractSlackChannelReferenceIds(
+        "<#C123> hi <#G456|private> and <#C123> again",
+      ),
+    ).toEqual(["C123", "G456"]);
+  });
+});
+
 describe("renderSlackTextForModel", () => {
   test("renders resolved user mentions", () => {
     expect(
       renderSlackTextForModel("hello <@U123>", {
         userLabels: { U123: "Alice" },
-      })
+      }),
     ).toBe("hello @Alice");
   });
 
@@ -36,7 +48,7 @@ describe("renderSlackTextForModel", () => {
     expect(
       renderSlackTextForModel("hello <@U123>", {
         userLabels: { U123: "U123" },
-      })
+      }),
     ).toBe("hello @unknown-user");
   });
 
@@ -44,29 +56,61 @@ describe("renderSlackTextForModel", () => {
     expect(
       renderSlackTextForModel("<#C123|general> <#C456>", {
         channelLabels: { C456: "support" },
-      })
+      }),
     ).toBe("#general #support");
 
     expect(renderSlackTextForModel("<#C789>")).toBe("#unknown-channel");
   });
 
+  test("prefers embedded Slack labels over resolved channel labels", () => {
+    expect(
+      renderSlackTextForModel("<#C123|old-name>", {
+        channelLabels: { C123: "new-name" },
+      }),
+    ).toBe("#old-name");
+  });
+
+  test("falls back to embedded channel labels when resolved labels are empty", () => {
+    expect(
+      renderSlackTextForModel("<#C123|general> <#C456|ops>", {
+        channelLabels: { C123: "", C456: "   " },
+      }),
+    ).toBe("#general #ops");
+  });
+
+  test("does not emit raw channel IDs from embedded or resolved labels", () => {
+    expect(
+      renderSlackTextForModel("<#C123|C123> <#C456|general>", {
+        channelLabels: { C456: "C456" },
+      }),
+    ).toBe("#unknown-channel #general");
+  });
+
+  test("uses resolved channel labels when embedded labels are missing or ID-shaped", () => {
+    expect(
+      renderSlackTextForModel("<#C123> <#C456|C456>", {
+        channelLabels: { C123: "general", C456: "ops" },
+      }),
+    ).toBe("#general #ops");
+  });
+
   test("renders special broadcasts", () => {
     expect(renderSlackTextForModel("<!here> <!channel> <!everyone>")).toBe(
-      "@here @channel @everyone"
+      "@here @channel @everyone",
     );
   });
 
   test("renders usergroups with labels and fallback", () => {
     expect(renderSlackTextForModel("<!subteam^S123|eng> <!subteam^S456>")).toBe(
-      "@eng @usergroup"
+      "@eng @usergroup",
     );
   });
 
   test("renders labeled and unlabeled links", () => {
     expect(
       renderSlackTextForModel(
-        "<https://example.com|Example> <https://example.org>"
-      )
+        "<https://example.com|Example> <https://example.org>",
+      ),
     ).toBe("Example (https://example.com) https://example.org");
   });
 
@@ -77,8 +121,8 @@ describe("renderSlackTextForModel", () => {
         {
           userLabels: { U123: " @<system>  prompt " },
           channelLabels: { C123: "#<ops>" },
-        }
-      )
+        },
+      ),
     ).toBe("@system prompt #ops #unknown-channel @eng");
   });
 
@@ -87,7 +131,7 @@ describe("renderSlackTextForModel", () => {
       renderSlackTextForModel("<@U123> <#C123>", {
         userFallbackLabel: "@ missing user ",
         channelFallbackLabel: "# missing channel ",
-      })
+      }),
     ).toBe("@missing user #missing channel");
   });
 });
@@ -101,7 +145,7 @@ describe("buildSlackUserLabelMap", () => {
         resolved.push(userId);
         if (userId === "U999") return "Charlie";
         return userId === "W456" ? "Bob" : "Alice";
-      }
+      },
     );
 
     expect(resolved.sort()).toEqual(["U123", "U999", "W456"]);
@@ -115,7 +159,7 @@ describe("buildSlackUserLabelMap", () => {
         if (userId === "UBOT") return "vex";
         if (userId === "ULEO") return "leo";
         return undefined;
-      }
+      },
     );
 
     expect(labels).toEqual({ UBOT: "vex", ULEO: "leo" });
@@ -128,9 +172,65 @@ describe("buildSlackUserLabelMap", () => {
         if (userId === "U123") return "U123";
         if (userId === "U456") return "";
         return "Alice";
-      }
+      },
     );
 
     expect(labels).toEqual({ U789: "Alice" });
   });
 });
+
+describe("buildSlackChannelLabelMap", () => {
+  test("dedupes unlabeled channel references and resolves them in parallel", async () => {
+    const resolved: string[] = [];
+    const labels = await buildSlackChannelLabelMap(
+      ["<#C123> hi <#G999> <#G999>", undefined, "<#C123> and <#D456>"],
+      async (channelId) => {
+        resolved.push(channelId);
+        if (channelId === "G999") return "private-team";
+        return channelId === "D456" ? "direct-chat" : "general";
+      },
+    );
+
+    expect(resolved.sort()).toEqual(["C123", "D456", "G999"]);
+    expect(labels).toEqual({
+      C123: "general",
+      D456: "direct-chat",
+      G999: "private-team",
+    });
+  });
+
+  test("does not resolve channel references that already have usable embedded labels", async () => {
+    const resolved: string[] = [];
+    const labels = await buildSlackChannelLabelMap(
+      ["<#C123|general> <#C456> <#C789|C789> <#CEMPTY|   >"],
+      async (channelId) => {
+        resolved.push(channelId);
+        return channelId === "C456"
+          ? "support"
+          : channelId === "CEMPTY"
+            ? "empty-label"
+            : "resolved";
+      },
+    );
+
+    expect(resolved.sort()).toEqual(["C456", "C789", "CEMPTY"]);
+    expect(labels).toEqual({
+      C456: "support",
+      C789: "resolved",
+      CEMPTY: "empty-label",
+    });
+  });
+
+  test("omits unresolved labels and labels equal to the Slack channel ID", async () => {
+    const labels = await buildSlackChannelLabelMap(
+      ["<#C123> <#C456> <#C789>"],
+      async (channelId) => {
+        if (channelId === "C123") return "C123";
+        if (channelId === "C456") return "";
+        return "support";
+      },
+    );
+
+    expect(labels).toEqual({ C789: "support" });
+  });
+});

package/node_modules/@vellumai/slack-text/src/index.ts

@@ -6,6 +6,7 @@ export interface RenderSlackTextOptions {
 }
 
 const SLACK_USER_MENTION_RE = /<@([UW][A-Z0-9]+)>/g;
+const SLACK_CHANNEL_REFERENCE_RE = /<#([CDG][A-Z0-9]+)(?:\|[^>]*)?>/g;
 
 export function extractSlackUserMentionIds(text: string): string[] {
   const seen = new Set<string>();
@@ -22,9 +23,24 @@ export function extractSlackUserMentionIds(text: string): string[] {
   return ids;
 }
 
+export function extractSlackChannelReferenceIds(text: string): string[] {
+  const seen = new Set<string>();
+  const ids: string[] = [];
+
+  for (const match of text.matchAll(SLACK_CHANNEL_REFERENCE_RE)) {
+    const id = match[1];
+    if (!seen.has(id)) {
+      seen.add(id);
+      ids.push(id);
+    }
+  }
+
+  return ids;
+}
+
 export function renderSlackTextForModel(
   text: string,
-  options: RenderSlackTextOptions = {}
+  options: RenderSlackTextOptions = {},
 ): string {
   return text.replace(/<([^<>\s][^<>]*)>/g, (token, content: string) => {
     if (content.startsWith("@")) {
@@ -49,7 +65,7 @@ export function renderSlackTextForModel(
 
 export async function buildSlackUserLabelMap(
   texts: Iterable<string | undefined>,
-  resolveLabel: (userId: string) => Promise<string | undefined | null>
+  resolveLabel: (userId: string) => Promise<string | undefined | null>,
 ): Promise<Record<string, string>> {
   const ids: string[] = [];
   const seen = new Set<string>();
@@ -66,18 +82,55 @@ export async function buildSlackUserLabelMap(
   if (ids.length === 0) return {};
 
   const entries = await Promise.all(
-    ids.map(
-      async (id): Promise<[string, string] | undefined> => {
-        try {
-          const label = await resolveLabel(id);
-          const sanitized = sanitizeOptionalLabel(label ?? undefined);
-          if (!sanitized || sanitized === id) return undefined;
-          return [id, sanitized];
-        } catch {
-          return undefined;
-        }
+    ids.map(async (id): Promise<[string, string] | undefined> => {
+      try {
+        const label = await resolveLabel(id);
+        const sanitized = sanitizeOptionalLabel(label ?? undefined);
+        if (!sanitized || sanitized === id) return undefined;
+        return [id, sanitized];
+      } catch {
+        return undefined;
+      }
+    }),
+  );
+
+  return Object.fromEntries(entries.filter((entry) => entry !== undefined));
+}
+
+export async function buildSlackChannelLabelMap(
+  texts: Iterable<string | undefined>,
+  resolveLabel: (channelId: string) => Promise<string | undefined | null>,
+): Promise<Record<string, string>> {
+  const ids: string[] = [];
+  const seen = new Set<string>();
+
+  for (const text of texts) {
+    if (!text) continue;
+    for (const match of text.matchAll(SLACK_CHANNEL_REFERENCE_RE)) {
+      const id = match[1];
+      const [, embeddedLabel] = splitSlackLabel(match[0].slice(1, -1));
+      const sanitizedEmbeddedLabel = sanitizeOptionalLabel(embeddedLabel);
+      if (sanitizedEmbeddedLabel && sanitizedEmbeddedLabel !== id) continue;
+      if (!seen.has(id)) {
+        seen.add(id);
+        ids.push(id);
+      }
+    }
+  }
+
+  if (ids.length === 0) return {};
+
+  const entries = await Promise.all(
+    ids.map(async (id): Promise<[string, string] | undefined> => {
+      try {
+        const label = await resolveLabel(id);
+        const sanitized = sanitizeOptionalLabel(label ?? undefined);
+        if (!sanitized || sanitized === id) return undefined;
+        return [id, sanitized];
+      } catch {
+        return undefined;
       }
-    )
+    }),
   );
 
   return Object.fromEntries(entries.filter((entry) => entry !== undefined));
@@ -85,7 +138,7 @@ export async function buildSlackUserLabelMap(
 
 function renderUserMention(
   content: string,
-  options: RenderSlackTextOptions
+  options: RenderSlackTextOptions,
 ): string {
   const id = content.slice(1);
   if (!isSlackUserId(id)) {
@@ -102,16 +155,27 @@ function renderUserMention(
 
 function renderChannelReference(
   content: string,
-  options: RenderSlackTextOptions
+  options: RenderSlackTextOptions,
 ): string {
   const [idWithPrefix, label] = splitSlackLabel(content);
   const channelId = idWithPrefix.slice(1);
   const fallback = sanitizeLabel(
     options.channelFallbackLabel,
-    "unknown-channel"
+    "unknown-channel",
   );
-  const resolvedLabel = label ?? options.channelLabels?.[channelId];
-  return `#${sanitizeLabel(resolvedLabel, fallback)}`;
+  const embeddedLabel = sanitizeOptionalLabel(label);
+  if (embeddedLabel && embeddedLabel !== channelId) {
+    return `#${embeddedLabel}`;
+  }
+
+  const resolvedLabel = sanitizeOptionalLabel(
+    options.channelLabels?.[channelId],
+  );
+  if (resolvedLabel && resolvedLabel !== channelId) {
+    return `#${resolvedLabel}`;
+  }
+
+  return `#${fallback}`;
 }
 
 function renderSpecialReference(content: string): string {