@vellumai/assistant 0.11.1 → 0.11.2-dev.202608042227.b54139c

package/Dockerfile

@@ -22,9 +22,7 @@ ENV PATH="/root/.bun/bin:${PATH}"
 # Note that we don't need source code to resolve cross-workspace dependencies.
 COPY package.json bun.lock ./
 COPY patches ./patches
-COPY clients/docs/package.json ./clients/docs/
-COPY clients/macos/package.json ./clients/macos/
-COPY clients/web/package.json ./clients/web/
+COPY --parents clients/*/package.json ./
 COPY cli/package.json ./cli/
 COPY gateway/package.json ./gateway/
 COPY credential-executor/package.json ./credential-executor/

package/README.md

@@ -28,7 +28,7 @@ For assistant architecture deep dives, see [`ARCHITECTURE.md`](ARCHITECTURE.md)
 
 ```bash
 cd assistant
-bun install
+bun install   # installs the whole workspace
 cp .env.example .env
 # Edit .env with your API keys
 ```

package/eslint.config.mjs

@@ -49,14 +49,29 @@ const eslintConfig = defineConfig([
       "@typescript-eslint/no-explicit-any": "off",
     },
   },
-  // Managed-column profile resolution (`getEffectiveProfile(s)`) resolves
-  // default profiles against the vellum column only, ignoring
-  // `llm.defaultProvider`; on a BYO install that is not the body that
-  // dispatches. Runtime code must use `resolveDefaultProfileForProvider` /
-  // `getEffectiveProfilesForProvider` instead. The allowlist below is the
-  // full set of intentional managed-column consumers: the catalog itself,
-  // hatch-time seeding (writes managed stubs by design), and write-path
-  // validation.
+  // Two unrelated import bans share one `no-restricted-imports` entry on
+  // purpose: flat config replaces rule options rather than merging them, so a
+  // second block setting the same rule over overlapping files would silently
+  // drop the first one's patterns.
+  //
+  // 1. Managed-column profile resolution (`getEffectiveProfile(s)`) resolves
+  //    default profiles against the vellum column only, ignoring
+  //    `llm.defaultProvider`; on a BYO install that is not the body that
+  //    dispatches. Runtime code must use `resolveDefaultProfileForProvider` /
+  //    `getEffectiveProfilesForProvider` instead. The allowlist below is the
+  //    full set of intentional managed-column consumers: the catalog itself,
+  //    hatch-time seeding (writes managed stubs by design), and write-path
+  //    validation.
+  //
+  // 2. `cli/logger` is the plain-stdout writer for short-lived `assistant …`
+  //    invocations. It has no level filtering and no log-file routing, so a
+  //    daemon-side module reaching for it writes debug output straight to a
+  //    stdout the daemon may not own. Daemon code uses `getLogger()` from
+  //    `util/logger.js`. The pattern matches on the import specifier, so
+  //    CLI-internal files (which reach their logger relatively, as
+  //    `../logger.js`) are unaffected. The companion guard test
+  //    `src/__tests__/cli-logger-boundary-guard.test.ts` enforces the same
+  //    boundary by resolved path, independent of how a specifier is spelled.
   {
     files: ["src/**/*.ts"],
     ignores: [
@@ -77,6 +92,11 @@ const eslintConfig = defineConfig([
               message:
                 "Managed-column resolution ignores llm.defaultProvider. Use resolveDefaultProfileForProvider / getEffectiveProfilesForProvider with the parsed config's llm.defaultProvider ?? null.",
             },
+            {
+              group: ["**/cli/logger.js"],
+              message:
+                "cli/logger writes unfiltered plain text to stdout and is for src/cli/ only. Daemon and shared modules must use getLogger() from util/logger.js so output is level-filtered and routed to the log file. Within src/cli/, import the logger relatively (../logger.js).",
+            },
           ],
         },
       ],

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/package.json

@@ -19,6 +19,7 @@
     "./attachment-naming": "./src/attachment-naming.ts",
     "./redacted-credential": "./src/redacted-credential.ts",
     "./secret-detection": "./src/secret-detection.ts",
+    "./stripe-currency": "./src/stripe-currency.ts",
     "./error": "./src/error.ts"
   },
   "scripts": {

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/__tests__/stripe-currency.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  STRIPE_THREE_DECIMAL_CURRENCIES,
+  STRIPE_ZERO_DECIMAL_CURRENCIES,
+  stripeScaleDigits,
+} from "../stripe-currency.js";
+
+describe("stripeScaleDigits", () => {
+  test("zero-decimal currencies scale to 0 digits", () => {
+    expect(stripeScaleDigits("JPY")).toBe(0);
+    expect(stripeScaleDigits("KRW")).toBe(0);
+  });
+
+  test("three-decimal currencies scale to 3 digits", () => {
+    expect(stripeScaleDigits("BHD")).toBe(3);
+    expect(stripeScaleDigits("KWD")).toBe(3);
+  });
+
+  test("everything else scales to 2 digits", () => {
+    expect(stripeScaleDigits("USD")).toBe(2);
+    expect(stripeScaleDigits("EUR")).toBe(2);
+    expect(stripeScaleDigits("XYZ")).toBe(2);
+  });
+
+  test("Stripe's charge-side two-decimal special cases stay at 2 digits", () => {
+    for (const code of ["ISK", "HUF", "TWD", "UGX"]) {
+      expect(stripeScaleDigits(code)).toBe(2);
+    }
+  });
+
+  test("the currency sets do not overlap", () => {
+    for (const code of STRIPE_ZERO_DECIMAL_CURRENCIES) {
+      expect(STRIPE_THREE_DECIMAL_CURRENCIES.has(code)).toBe(false);
+    }
+  });
+});

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/stripe-currency.ts

@@ -0,0 +1,55 @@
+/**
+ * Stripe amount scaling rules for charges and invoices.
+ *
+ * These sets follow Stripe's amount scaling rules
+ * (https://docs.stripe.com/currencies), not ISO 4217 metadata: divide the
+ * minor-unit integer by 100 for most currencies, by 1 for the zero-decimal
+ * set (e.g. JPY, KRW), and by 1000 for the three-decimal set (e.g. BHD).
+ * ISK, HUF, TWD, and UGX are deliberately absent from the zero-decimal set:
+ * Stripe charges and invoices them as two-decimal amounts and treats them
+ * as zero-decimal only for payouts, per Stripe's currency docs.
+ *
+ * Only the scaling data and digit selection live here; presentation (locale,
+ * symbol vs code display, fallbacks for unknown codes) belongs to each
+ * consumer.
+ */
+export const STRIPE_ZERO_DECIMAL_CURRENCIES: ReadonlySet<string> = new Set([
+  "BIF",
+  "CLP",
+  "DJF",
+  "GNF",
+  "JPY",
+  "KMF",
+  "KRW",
+  "MGA",
+  "PYG",
+  "RWF",
+  "VND",
+  "VUV",
+  "XAF",
+  "XOF",
+  "XPF",
+]);
+
+export const STRIPE_THREE_DECIMAL_CURRENCIES: ReadonlySet<string> = new Set([
+  "BHD",
+  "JOD",
+  "KWD",
+  "OMR",
+  "TND",
+]);
+
+/**
+ * Fraction digits Stripe uses when charging or invoicing in the given
+ * currency. Expects an uppercase ISO 4217 code; unknown codes get the
+ * two-decimal default.
+ */
+export function stripeScaleDigits(currencyCode: string): number {
+  if (STRIPE_ZERO_DECIMAL_CURRENCIES.has(currencyCode)) {
+    return 0;
+  }
+  if (STRIPE_THREE_DECIMAL_CURRENCIES.has(currencyCode)) {
+    return 3;
+  }
+  return 2;
+}

package/node_modules/@vellumai/environments/src/__tests__/install-layout.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Tests for reading an install layout: telling a repo checkout from an
+ * installed package, and locating the `assistant` command that ships with an
+ * install.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { findAssistantCommand, isRepoCheckoutPath } from "../index.js";
+
+let root: string;
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "install-layout-"));
+});
+
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+/** Create `<nodeModulesDir>/.bin/assistant` and return its path. */
+function seedCommand(nodeModulesDir: string): string {
+  const binDir = join(nodeModulesDir, ".bin");
+  mkdirSync(binDir, { recursive: true });
+  const command = join(binDir, "assistant");
+  writeFileSync(command, "#!/usr/bin/env bun\n");
+  return command;
+}
+
+describe("isRepoCheckoutPath", () => {
+  test("an installed package is not a checkout", () => {
+    expect(
+      isRepoCheckoutPath(
+        "/Users/x/Library/Application Support/@vellumai/macos/cli/latest/node_modules/@vellumai/assistant/src/index.ts",
+      ),
+    ).toBe(false);
+  });
+
+  test("a repo checkout is", () => {
+    expect(
+      isRepoCheckoutPath("/Users/x/dev/vellum/assistant/src/index.ts"),
+    ).toBe(true);
+  });
+
+  test("a directory merely named node_modules-ish is not enough", () => {
+    expect(
+      isRepoCheckoutPath("/Users/x/node_modules_backup/a/src/index.ts"),
+    ).toBe(true);
+  });
+});
+
+describe("findAssistantCommand", () => {
+  test("finds the command shipped beside an installed package", () => {
+    const nodeModules = join(root, "cli", "latest", "node_modules");
+    const command = seedCommand(nodeModules);
+    const path = join(nodeModules, "@vellumai", "assistant", "src", "index.ts");
+
+    expect(findAssistantCommand(path)).toBe(command);
+  });
+
+  test("prefers a nested install over a hoisted one", () => {
+    const outer = join(root, "node_modules");
+    const outerCommand = seedCommand(outer);
+    const inner = join(outer, "vellum", "node_modules");
+    const innerCommand = seedCommand(inner);
+    const path = join(inner, "@vellumai", "assistant", "src", "index.ts");
+
+    expect(findAssistantCommand(path)).toBe(innerCommand);
+    expect(innerCommand).not.toBe(outerCommand);
+  });
+
+  test("falls back to a hoisted install when the nested one has no command", () => {
+    const outer = join(root, "node_modules");
+    const outerCommand = seedCommand(outer);
+    const inner = join(outer, "vellum", "node_modules");
+    mkdirSync(inner, { recursive: true });
+    const path = join(inner, "@vellumai", "assistant", "src", "index.ts");
+
+    expect(findAssistantCommand(path)).toBe(outerCommand);
+  });
+
+  test("returns null for a repo checkout", () => {
+    expect(
+      findAssistantCommand(join(root, "assistant", "src", "index.ts")),
+    ).toBeNull();
+  });
+
+  test("returns null when the install ships no assistant command", () => {
+    const nodeModules = join(root, "node_modules");
+    mkdirSync(join(nodeModules, ".bin"), { recursive: true });
+    const path = join(nodeModules, "@vellumai", "assistant", "src", "index.ts");
+
+    expect(findAssistantCommand(path)).toBeNull();
+  });
+});

package/node_modules/@vellumai/environments/src/__tests__/package-boundary.test.ts

@@ -1,10 +1,10 @@
 /**
  * Package boundary tests for @vellumai/environments.
  *
- * This package is the lowest layer of the shared-packages hierarchy: pure
- * environment types and constants with no runtime dependencies. It must
- * stay a leaf so any consumer (CLI, assistant, local-mode host) can depend
- * on it without dragging in a dependency tree.
+ * This package is the lowest layer of the shared-packages hierarchy:
+ * environment types, constants, and small helpers over node builtins, with no
+ * runtime dependencies. It must stay a leaf so any consumer (CLI, assistant,
+ * local-mode host) can depend on it without dragging in a dependency tree.
  *
  * Enforces that the package:
  * 1. Imports only node builtins and its own relative modules — no `@vellumai/*`
@@ -79,7 +79,7 @@ describe("package boundary", () => {
       throw new Error(
         `Found ${violations.length} forbidden import(s) in @vellumai/environments:\n` +
           violations.map((v) => `  - ${v}`).join("\n") +
-          "\n\n@vellumai/environments is a pure types/constants leaf and must\n" +
+          "\n\n@vellumai/environments is a dependency-free leaf and must\n" +
           "import only node builtins and its own relative modules.",
       );
     }

package/node_modules/@vellumai/environments/src/index.ts

@@ -1,11 +1,22 @@
 /**
- * @vellumai/environments — the single source of truth for Vellum's known
- * deployment environments (names, platform/web URLs, per-service port
- * blocks). Consumed by the CLI, the assistant daemon, and the local-mode
- * host library so the environment list is defined exactly once on the TS
- * side. The Swift client mirrors the same set in `VellumEnvironment.swift`.
+ * @vellumai/environments: the single source of truth for how a Vellum install
+ * is laid out and which deployment environment it belongs to.
  *
- * Intentionally free of runtime dependencies: pure types and constants only.
+ * Two things live here:
+ *
+ *   - The known deployment environments (names, platform/web URLs, per-service
+ *     port blocks). The Swift client mirrors the same set in
+ *     `VellumEnvironment.swift`.
+ *   - Install layout: whether a runtime is a repo checkout or an installed
+ *     package, and where the `assistant` command it ships lives.
+ *
+ * Consumed by the CLI, the assistant daemon, and the local-mode host library
+ * so each answer is defined exactly once on the TS side.
+ *
+ * This is the lowest layer of the shared-packages hierarchy and stays a leaf:
+ * types, constants, and small helpers over node builtins, with no runtime
+ * dependencies of its own. See `__tests__/package-boundary.test.ts`.
  */
 export * from "./types.js";
 export * from "./seeds.js";
+export * from "./install-layout.js";

package/node_modules/@vellumai/environments/src/install-layout.ts

@@ -0,0 +1,49 @@
+/**
+ * Reading the layout a Vellum runtime is installed in.
+ *
+ * The daemon is started either from a developer's repo checkout or from an
+ * installed npm package (`<install>/node_modules/@vellumai/assistant/src/
+ * index.ts`, which is what the desktop app runs). The CLI needs the layout to
+ * decide whether a launch is a dev run and what to put on the daemon's PATH;
+ * the daemon needs it to decide what to install as the `assistant` command.
+ * Both ask the same two questions, so they ask them here.
+ */
+
+import { existsSync } from "node:fs";
+import { join, sep } from "node:path";
+
+const NODE_MODULES_SEGMENT = `${sep}node_modules${sep}`;
+
+/**
+ * Whether `path` sits in a developer's repo checkout rather than inside an
+ * installed package.
+ */
+export function isRepoCheckoutPath(path: string): boolean {
+  return !path.includes(NODE_MODULES_SEGMENT);
+}
+
+/**
+ * The `assistant` command shipped with the install that contains `path`, or
+ * null when there is none (a repo checkout, or an install whose dependency
+ * graph omits the package declaring the bin).
+ *
+ * Searches innermost `node_modules` outward, since a nested install shadows a
+ * hoisted one.
+ */
+export function findAssistantCommand(path: string): string | null {
+  let index = path.lastIndexOf(NODE_MODULES_SEGMENT);
+
+  while (index !== -1) {
+    const nodeModulesDir = path.slice(
+      0,
+      index + NODE_MODULES_SEGMENT.length - 1,
+    );
+    const command = join(nodeModulesDir, ".bin", "assistant");
+    if (existsSync(command)) {
+      return command;
+    }
+    index = path.lastIndexOf(NODE_MODULES_SEGMENT, index - 1);
+  }
+
+  return null;
+}

package/node_modules/@vellumai/gateway-client/node_modules/@vellumai/service-contracts/package.json

@@ -19,6 +19,7 @@
     "./attachment-naming": "./src/attachment-naming.ts",
     "./redacted-credential": "./src/redacted-credential.ts",
     "./secret-detection": "./src/secret-detection.ts",
+    "./stripe-currency": "./src/stripe-currency.ts",
     "./error": "./src/error.ts"
   },
   "scripts": {

package/node_modules/@vellumai/gateway-client/node_modules/@vellumai/service-contracts/src/__tests__/stripe-currency.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  STRIPE_THREE_DECIMAL_CURRENCIES,
+  STRIPE_ZERO_DECIMAL_CURRENCIES,
+  stripeScaleDigits,
+} from "../stripe-currency.js";
+
+describe("stripeScaleDigits", () => {
+  test("zero-decimal currencies scale to 0 digits", () => {
+    expect(stripeScaleDigits("JPY")).toBe(0);
+    expect(stripeScaleDigits("KRW")).toBe(0);
+  });
+
+  test("three-decimal currencies scale to 3 digits", () => {
+    expect(stripeScaleDigits("BHD")).toBe(3);
+    expect(stripeScaleDigits("KWD")).toBe(3);
+  });
+
+  test("everything else scales to 2 digits", () => {
+    expect(stripeScaleDigits("USD")).toBe(2);
+    expect(stripeScaleDigits("EUR")).toBe(2);
+    expect(stripeScaleDigits("XYZ")).toBe(2);
+  });
+
+  test("Stripe's charge-side two-decimal special cases stay at 2 digits", () => {
+    for (const code of ["ISK", "HUF", "TWD", "UGX"]) {
+      expect(stripeScaleDigits(code)).toBe(2);
+    }
+  });
+
+  test("the currency sets do not overlap", () => {
+    for (const code of STRIPE_ZERO_DECIMAL_CURRENCIES) {
+      expect(STRIPE_THREE_DECIMAL_CURRENCIES.has(code)).toBe(false);
+    }
+  });
+});

package/node_modules/@vellumai/gateway-client/node_modules/@vellumai/service-contracts/src/stripe-currency.ts

@@ -0,0 +1,55 @@
+/**
+ * Stripe amount scaling rules for charges and invoices.
+ *
+ * These sets follow Stripe's amount scaling rules
+ * (https://docs.stripe.com/currencies), not ISO 4217 metadata: divide the
+ * minor-unit integer by 100 for most currencies, by 1 for the zero-decimal
+ * set (e.g. JPY, KRW), and by 1000 for the three-decimal set (e.g. BHD).
+ * ISK, HUF, TWD, and UGX are deliberately absent from the zero-decimal set:
+ * Stripe charges and invoices them as two-decimal amounts and treats them
+ * as zero-decimal only for payouts, per Stripe's currency docs.
+ *
+ * Only the scaling data and digit selection live here; presentation (locale,
+ * symbol vs code display, fallbacks for unknown codes) belongs to each
+ * consumer.
+ */
+export const STRIPE_ZERO_DECIMAL_CURRENCIES: ReadonlySet<string> = new Set([
+  "BIF",
+  "CLP",
+  "DJF",
+  "GNF",
+  "JPY",
+  "KMF",
+  "KRW",
+  "MGA",
+  "PYG",
+  "RWF",
+  "VND",
+  "VUV",
+  "XAF",
+  "XOF",
+  "XPF",
+]);
+
+export const STRIPE_THREE_DECIMAL_CURRENCIES: ReadonlySet<string> = new Set([
+  "BHD",
+  "JOD",
+  "KWD",
+  "OMR",
+  "TND",
+]);
+
+/**
+ * Fraction digits Stripe uses when charging or invoicing in the given
+ * currency. Expects an uppercase ISO 4217 code; unknown codes get the
+ * two-decimal default.
+ */
+export function stripeScaleDigits(currencyCode: string): number {
+  if (STRIPE_ZERO_DECIMAL_CURRENCIES.has(currencyCode)) {
+    return 0;
+  }
+  if (STRIPE_THREE_DECIMAL_CURRENCIES.has(currencyCode)) {
+    return 3;
+  }
+  return 2;
+}

package/node_modules/@vellumai/service-contracts/package.json

@@ -19,6 +19,7 @@
     "./attachment-naming": "./src/attachment-naming.ts",
     "./redacted-credential": "./src/redacted-credential.ts",
     "./secret-detection": "./src/secret-detection.ts",
+    "./stripe-currency": "./src/stripe-currency.ts",
     "./error": "./src/error.ts"
   },
   "scripts": {

package/node_modules/@vellumai/service-contracts/src/__tests__/stripe-currency.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  STRIPE_THREE_DECIMAL_CURRENCIES,
+  STRIPE_ZERO_DECIMAL_CURRENCIES,
+  stripeScaleDigits,
+} from "../stripe-currency.js";
+
+describe("stripeScaleDigits", () => {
+  test("zero-decimal currencies scale to 0 digits", () => {
+    expect(stripeScaleDigits("JPY")).toBe(0);
+    expect(stripeScaleDigits("KRW")).toBe(0);
+  });
+
+  test("three-decimal currencies scale to 3 digits", () => {
+    expect(stripeScaleDigits("BHD")).toBe(3);
+    expect(stripeScaleDigits("KWD")).toBe(3);
+  });
+
+  test("everything else scales to 2 digits", () => {
+    expect(stripeScaleDigits("USD")).toBe(2);
+    expect(stripeScaleDigits("EUR")).toBe(2);
+    expect(stripeScaleDigits("XYZ")).toBe(2);
+  });
+
+  test("Stripe's charge-side two-decimal special cases stay at 2 digits", () => {
+    for (const code of ["ISK", "HUF", "TWD", "UGX"]) {
+      expect(stripeScaleDigits(code)).toBe(2);
+    }
+  });
+
+  test("the currency sets do not overlap", () => {
+    for (const code of STRIPE_ZERO_DECIMAL_CURRENCIES) {
+      expect(STRIPE_THREE_DECIMAL_CURRENCIES.has(code)).toBe(false);
+    }
+  });
+});

package/node_modules/@vellumai/service-contracts/src/stripe-currency.ts

@@ -0,0 +1,55 @@
+/**
+ * Stripe amount scaling rules for charges and invoices.
+ *
+ * These sets follow Stripe's amount scaling rules
+ * (https://docs.stripe.com/currencies), not ISO 4217 metadata: divide the
+ * minor-unit integer by 100 for most currencies, by 1 for the zero-decimal
+ * set (e.g. JPY, KRW), and by 1000 for the three-decimal set (e.g. BHD).
+ * ISK, HUF, TWD, and UGX are deliberately absent from the zero-decimal set:
+ * Stripe charges and invoices them as two-decimal amounts and treats them
+ * as zero-decimal only for payouts, per Stripe's currency docs.
+ *
+ * Only the scaling data and digit selection live here; presentation (locale,
+ * symbol vs code display, fallbacks for unknown codes) belongs to each
+ * consumer.
+ */
+export const STRIPE_ZERO_DECIMAL_CURRENCIES: ReadonlySet<string> = new Set([
+  "BIF",
+  "CLP",
+  "DJF",
+  "GNF",
+  "JPY",
+  "KMF",
+  "KRW",
+  "MGA",
+  "PYG",
+  "RWF",
+  "VND",
+  "VUV",
+  "XAF",
+  "XOF",
+  "XPF",
+]);
+
+export const STRIPE_THREE_DECIMAL_CURRENCIES: ReadonlySet<string> = new Set([
+  "BHD",
+  "JOD",
+  "KWD",
+  "OMR",
+  "TND",
+]);
+
+/**
+ * Fraction digits Stripe uses when charging or invoicing in the given
+ * currency. Expects an uppercase ISO 4217 code; unknown codes get the
+ * two-decimal default.
+ */
+export function stripeScaleDigits(currencyCode: string): number {
+  if (STRIPE_ZERO_DECIMAL_CURRENCIES.has(currencyCode)) {
+    return 0;
+  }
+  if (STRIPE_THREE_DECIMAL_CURRENCIES.has(currencyCode)) {
+    return 3;
+  }
+  return 2;
+}

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

@@ -14,6 +14,36 @@ describe("extractSlackUserMentionIds", () => {
       extractSlackUserMentionIds("<@U123> hi <@W456> and <@U123> again"),
     ).toEqual(["U123", "W456"]);
   });
+
+  test("includes pipe-form user mention IDs", () => {
+    expect(extractSlackUserMentionIds("<@U123|jane> and <@W456|>")).toEqual([
+      "U123",
+      "W456",
+    ]);
+  });
+});
+
+describe("buildSlackUserLabelMap", () => {
+  test("skips pipe-form mentions with usable embedded labels, queues the rest", async () => {
+    const requested: string[] = [];
+    const labels = await buildSlackUserLabelMap(
+      ["<@U123|jane> <@U456|> <@U789|U789> <@U999>"],
+      async (id) => {
+        requested.push(id);
+        return `name-${id}`;
+      },
+    );
+
+    // Usable embedded label: rendered from the token, no lookup.
+    expect(requested).not.toContain("U123");
+    // Empty or ID-shaped embedded labels still need resolution.
+    expect(requested.sort()).toEqual(["U456", "U789", "U999"]);
+    expect(labels).toEqual({
+      U456: "name-U456",
+      U789: "name-U789",
+      U999: "name-U999",
+    });
+  });
 });
 
 describe("extractSlackChannelReferenceIds", () => {
@@ -52,6 +82,24 @@ describe("renderSlackTextForModel", () => {
     ).toBe("hello @unknown-user");
   });
 
+  test("prefers embedded pipe-form user labels over lookups", () => {
+    expect(renderSlackTextForModel("hi <@U123|jane>")).toBe("hi @jane");
+    expect(
+      renderSlackTextForModel("hi <@U123|jane>", {
+        userLabels: { U123: "Jane Doe" },
+      }),
+    ).toBe("hi @jane");
+  });
+
+  test("falls back past ID-shaped embedded user labels to resolved ones", () => {
+    expect(
+      renderSlackTextForModel("hi <@U123|U123>", {
+        userLabels: { U123: "Jane Doe" },
+      }),
+    ).toBe("hi @Jane Doe");
+    expect(renderSlackTextForModel("hi <@U123|U123>")).toBe("hi @unknown-user");
+  });
+
   test("renders channel references with labels and fallbacks", () => {
     expect(
       renderSlackTextForModel("<#C123|general> <#C456>", {