@vellumai/assistant 0.4.41 → 0.4.43

package/src/config/skills.ts

@@ -15,6 +15,9 @@ import {
   resolve,
 } from "node:path";
 
+import { z } from "zod";
+
+import { stripCommentLines } from "../prompts/system-prompt.js";
 import {
   extractAllText,
   getConfiguredProvider,
@@ -25,10 +28,57 @@ import { parseToolManifestFile } from "../skills/tool-manifest.js";
 import { computeSkillVersionHash } from "../skills/version-hash.js";
 import { getLogger } from "../util/logger.js";
 import { getWorkspaceSkillsDir } from "../util/platform.js";
-import { stripCommentLines } from "./system-prompt.js";
+import { isAssistantFeatureFlagEnabled } from "./assistant-feature-flags.js";
+import { getConfig } from "./loader.js";
 
 const log = getLogger("skills");
 
+// ─── Zod schemas for frontmatter metadata validation ─────────────────────────
+
+const VellumMetadataSchema = z
+  .object({
+    emoji: z.string().optional(),
+    os: z.array(z.string()).optional(),
+    requires: z
+      .object({
+        bins: z.array(z.string()).optional(),
+        anyBins: z.array(z.string()).optional(),
+        env: z.array(z.string()).optional(),
+        config: z.array(z.string()).optional(),
+      })
+      .optional(),
+    primaryEnv: z.string().optional(),
+    install: z
+      .array(
+        z
+          .object({
+            id: z.string(),
+            kind: z.enum(["brew", "node", "go", "uv", "download"]),
+          })
+          .passthrough(),
+      )
+      .optional(),
+    cli: z
+      .object({
+        command: z.string(),
+        entry: z.string(),
+      })
+      .optional(),
+    "display-name": z.string().optional(),
+    "user-invocable": z.union([z.boolean(), z.string()]).optional(),
+    "disable-model-invocation": z.union([z.boolean(), z.string()]).optional(),
+    includes: z.array(z.string()).optional(),
+    "credential-setup-for": z.string().optional(),
+  })
+  .passthrough();
+
+const SkillMetadataSchema = z
+  .object({
+    emoji: z.string().optional(),
+    vellum: VellumMetadataSchema.optional(),
+  })
+  .passthrough();
+
 // ─── New interfaces for extended skill metadata ──────────────────────────────
 
 export interface SkillCliSpec {
@@ -68,6 +118,7 @@ export type SkillSource = "bundled" | "managed" | "workspace" | "extra";
 export interface SkillSummary {
   id: string;
   name: string;
+  displayName: string;
   description: string;
   directoryPath: string;
   skillFilePath: string;
@@ -270,9 +321,9 @@ function getSkillsIndexPath(skillsDir: string): string {
 
 interface ParsedFrontmatter {
   name: string;
+  displayName: string;
   description: string;
   body: string;
-  homepage?: string;
   userInvocable: boolean;
   disableModelInvocation: boolean;
   metadata?: VellumMetadata;
@@ -280,47 +331,6 @@ interface ParsedFrontmatter {
   credentialSetupFor?: string;
 }
 
-function parseIncludes(
-  raw: string | undefined,
-  skillFilePath: string,
-): string[] | undefined {
-  if (!raw) return undefined;
-
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (err) {
-    log.warn(
-      { err, skillFilePath },
-      "Failed to parse includes JSON in frontmatter",
-    );
-    return undefined;
-  }
-
-  if (!Array.isArray(parsed)) {
-    log.warn({ skillFilePath }, "includes must be a JSON array");
-    return undefined;
-  }
-
-  if (!parsed.every((item: unknown) => typeof item === "string")) {
-    log.warn({ skillFilePath }, "includes must be an array of strings");
-    return undefined;
-  }
-
-  // Normalize: trim, remove empty strings, deduplicate preserving first-seen order
-  const seen = new Set<string>();
-  const result: string[] = [];
-  for (const item of parsed as string[]) {
-    const trimmed = item.trim();
-    if (trimmed.length === 0) continue;
-    if (seen.has(trimmed)) continue;
-    seen.add(trimmed);
-    result.push(trimmed);
-  }
-
-  return result.length > 0 ? result : undefined;
-}
-
 function parseFrontmatter(
   content: string,
   skillFilePath: string,
@@ -343,25 +353,64 @@ function parseFrontmatter(
     return null;
   }
 
-  // Parse new optional fields
-  const homepage = fields.homepage?.trim() || undefined;
-
-  const userInvocableRaw = fields["user-invocable"]?.trim().toLowerCase();
-  const userInvocable = userInvocableRaw !== "false";
-
-  const disableModelInvocationRaw = fields["disable-model-invocation"]
-    ?.trim()
-    .toLowerCase();
-  const disableModelInvocation = disableModelInvocationRaw === "true";
-
-  // Parse metadata as single-line JSON string, extract .vellum namespace
+  // Parse metadata as single-line JSON string, validate with Zod schema
   let metadata: VellumMetadata | undefined;
+  let parsedMeta: z.infer<typeof SkillMetadataSchema> | undefined;
+  let vellum: z.infer<typeof VellumMetadataSchema> | undefined;
+
   const metadataRaw = fields.metadata?.trim();
   if (metadataRaw) {
     try {
-      const parsed = JSON.parse(metadataRaw);
-      if (parsed && typeof parsed === "object" && parsed.vellum) {
-        metadata = parsed.vellum as VellumMetadata;
+      const json = JSON.parse(metadataRaw);
+      const result = SkillMetadataSchema.safeParse(json);
+      if (result.success) {
+        parsedMeta = result.data;
+        vellum = parsedMeta.vellum;
+        if (parsedMeta.vellum) {
+          metadata = parsedMeta.vellum as VellumMetadata;
+        }
+        // Inject top-level emoji into metadata when metadata.vellum doesn't
+        // carry its own emoji. The Agent Skills spec places emoji at the
+        // top level of the metadata JSON, so bundled skills that follow
+        // this convention would otherwise lose their emoji value.
+        if (parsedMeta.emoji) {
+          if (metadata && !metadata.emoji) {
+            metadata.emoji = parsedMeta.emoji;
+          } else if (!metadata) {
+            metadata = { emoji: parsedMeta.emoji };
+          }
+        }
+      } else {
+        // Zod validation failed — fall back to raw JSON so we don't lose
+        // all metadata because of a single bad field value.  We coerce
+        // critical array fields so downstream code that iterates them
+        // (e.g. `.join()`, `for...of`, `.some()`) won't crash.
+        log.warn(
+          { err: result.error, skillFilePath },
+          "Metadata failed schema validation; falling back to raw JSON",
+        );
+        parsedMeta = json;
+        vellum = json?.vellum;
+        if (json?.vellum && typeof json.vellum === "object") {
+          const raw = json.vellum as Record<string, unknown>;
+
+          // Coerce `os` to string[] — a bare string is wrapped in an array.
+          if (raw.os !== undefined) {
+            raw.os = Array.isArray(raw.os) ? raw.os : [raw.os];
+          }
+
+          // Coerce `requires` sub-fields to arrays.
+          if (raw.requires && typeof raw.requires === "object") {
+            const req = raw.requires as Record<string, unknown>;
+            for (const key of ["bins", "anyBins", "env", "config"] as const) {
+              if (req[key] !== undefined && !Array.isArray(req[key])) {
+                req[key] = typeof req[key] === "string" ? [req[key]] : [];
+              }
+            }
+          }
+
+          metadata = raw as unknown as VellumMetadata;
+        }
       }
     } catch (err) {
       log.warn(
@@ -371,25 +420,55 @@ function parseFrontmatter(
     }
   }
 
-  // Read standalone emoji frontmatter field (written by buildSkillMarkdown)
-  const emojiField = fields.emoji?.trim() || undefined;
+  // Read vellum-specific fields exclusively from metadata.vellum
+  const vellumUserInvocable = vellum?.["user-invocable"];
+  let userInvocable: boolean;
+  if (typeof vellumUserInvocable === "boolean") {
+    userInvocable = vellumUserInvocable;
+  } else if (typeof vellumUserInvocable === "string") {
+    userInvocable = vellumUserInvocable !== "false";
+  } else {
+    userInvocable = true;
+  }
+
+  const vellumDisableModelInvocation = vellum?.["disable-model-invocation"];
+  let disableModelInvocation: boolean;
+  if (typeof vellumDisableModelInvocation === "boolean") {
+    disableModelInvocation = vellumDisableModelInvocation;
+  } else if (typeof vellumDisableModelInvocation === "string") {
+    disableModelInvocation = vellumDisableModelInvocation === "true";
+  } else {
+    disableModelInvocation = false;
+  }
 
-  // If metadata doesn't already have an emoji, inject the standalone field value
-  if (emojiField && metadata && !metadata.emoji) {
-    metadata.emoji = emojiField;
-  } else if (emojiField && !metadata) {
-    metadata = { emoji: emojiField };
+  let includes: string[] | undefined;
+  if (Array.isArray(vellum?.includes)) {
+    const normalized = [
+      ...new Set(
+        vellum.includes
+          .filter((item: unknown): item is string => typeof item === "string")
+          .map((s: string) => s.trim())
+          .filter((s: string) => s.length > 0),
+      ),
+    ];
+    includes = normalized.length > 0 ? normalized : undefined;
   }
 
-  const includes = parseIncludes(fields.includes, skillFilePath);
   const credentialSetupFor =
-    fields["credential-setup-for"]?.trim() || undefined;
+    typeof vellum?.["credential-setup-for"] === "string"
+      ? vellum["credential-setup-for"]
+      : undefined;
+
+  const displayName =
+    (typeof vellum?.["display-name"] === "string"
+      ? vellum["display-name"]
+      : undefined) ?? name;
 
   return {
     name,
+    displayName,
     description,
     body: stripCommentLines(body),
-    homepage,
     userInvocable,
     disableModelInvocation,
     metadata,
@@ -536,12 +615,12 @@ function readSkillFromDirectory(
     return {
       id: basename(directoryPath),
       name: parsed.name,
+      displayName: parsed.displayName,
       description: parsed.description,
       directoryPath,
       skillFilePath,
       body: parsed.body,
       emoji: parsed.metadata?.emoji,
-      homepage: parsed.homepage,
       userInvocable: parsed.userInvocable,
       disableModelInvocation: parsed.disableModelInvocation,
       source,
@@ -585,13 +664,13 @@ function readBundledSkillFromDirectory(
     return {
       id: basename(directoryPath),
       name: parsed.name,
+      displayName: parsed.displayName,
       description: parsed.description,
       directoryPath,
       skillFilePath,
       body: parsed.body,
       bundled: true,
       emoji: parsed.metadata?.emoji,
-      homepage: parsed.homepage,
       userInvocable: parsed.userInvocable,
       disableModelInvocation: parsed.disableModelInvocation,
       source: "bundled",
@@ -644,12 +723,12 @@ function loadBundledSkills(): SkillSummary[] {
     skills.push({
       id: skill.id,
       name: skill.name,
+      displayName: skill.displayName,
       description: skill.description,
       directoryPath: skill.directoryPath,
       skillFilePath: skill.skillFilePath,
       bundled: true,
       emoji: skill.emoji,
-      homepage: skill.homepage,
       userInvocable: skill.userInvocable,
       disableModelInvocation: skill.disableModelInvocation,
       source: "bundled",
@@ -781,12 +860,12 @@ function skillSummaryFromDefinition(
   return {
     id: skill.id,
     name: skill.name,
+    displayName: skill.displayName,
     description: skill.description,
     directoryPath: skill.directoryPath,
     skillFilePath: skill.skillFilePath,
     bundled: skill.bundled,
     emoji: skill.emoji,
-    homepage: skill.homepage,
     userInvocable: skill.userInvocable,
     disableModelInvocation: skill.disableModelInvocation,
     source,
@@ -834,11 +913,11 @@ export function loadSkillCatalog(
           catalog.push({
             id,
             name: parsed.name,
+            displayName: parsed.displayName ?? parsed.name,
             description: parsed.description,
             directoryPath: directory,
             skillFilePath,
             emoji: parsed.metadata?.emoji,
-            homepage: parsed.homepage,
             userInvocable: parsed.userInvocable,
             disableModelInvocation: parsed.disableModelInvocation,
             source: "extra",
@@ -930,11 +1009,11 @@ export function loadSkillCatalog(
         const workspaceSkill: SkillSummary = {
           id,
           name: parsed.name,
+          displayName: parsed.displayName ?? parsed.name,
           description: parsed.description,
           directoryPath: directory,
           skillFilePath,
           emoji: parsed.metadata?.emoji,
-          homepage: parsed.homepage,
           userInvocable: parsed.userInvocable,
           disableModelInvocation: parsed.disableModelInvocation,
           source: "workspace",
@@ -968,6 +1047,79 @@ export function loadSkillCatalog(
   return catalog;
 }
 
+/**
+ * Process feature-gated sections in skill body markdown.
+ *
+ * Markers:
+ *   <!-- feature:<flag-id>:start --> ... <!-- feature:<flag-id>:end -->
+ *     Content included only when the flag is enabled.
+ *   <!-- feature:<flag-id>:alt --> ... <!-- feature:<flag-id>:alt:end -->
+ *     Fallback content included only when the flag is disabled.
+ */
+function applyFeatureGatedSections(body: string): string {
+  const config = getConfig();
+  // Match feature:*:start/end blocks
+  const mainRe =
+    /<!-- feature:([^:]+):start -->\n?([\s\S]*?)<!-- feature:\1:end -->\n?/g;
+  // Match feature:*:alt/alt:end blocks
+  const altRe =
+    /<!-- feature:([^:]+):alt -->\n?([\s\S]*?)<!-- feature:\1:alt:end -->\n?/g;
+
+  let result = body;
+
+  result = result.replace(mainRe, (_match, flagId: string, content: string) => {
+    const key = `feature_flags.${flagId}.enabled`;
+    return isAssistantFeatureFlagEnabled(key, config) ? content : "";
+  });
+
+  result = result.replace(altRe, (_match, flagId: string, content: string) => {
+    const key = `feature_flags.${flagId}.enabled`;
+    return isAssistantFeatureFlagEnabled(key, config) ? "" : content;
+  });
+
+  return result;
+}
+
+/**
+ * Scan for a `references/` subdirectory within a skill directory and append
+ * the contents of any `.md` files found there to the skill body. Each
+ * reference file is labeled with a `--- Reference: <Name> ---` header.
+ * Files are appended in alphabetical order for deterministic output.
+ * Non-`.md` files are ignored. Errors are logged as warnings and the
+ * original body is returned unchanged.
+ */
+function appendReferenceFiles(body: string, directoryPath: string): string {
+  try {
+    const refsDir = join(directoryPath, "references");
+    if (!existsSync(refsDir) || !statSync(refsDir).isDirectory()) {
+      return body;
+    }
+
+    const entries = readdirSync(refsDir);
+    const mdFiles = entries
+      .filter((f) => f.toLowerCase().endsWith(".md"))
+      .sort((a, b) => a.localeCompare(b));
+
+    if (mdFiles.length === 0) return body;
+
+    let result = body;
+    for (const filename of mdFiles) {
+      const fileContents = readFileSync(join(refsDir, filename), "utf-8");
+      const displayName = filename
+        .replace(/\.md$/i, "")
+        .replace(/[-_]/g, " ")
+        .replace(/\b\w/g, (c) => c.toUpperCase())
+        .replace(/\B\w+/g, (w) => w.toLowerCase());
+      result += `\n\n--- Reference: ${displayName} ---\n${fileContents}`;
+    }
+
+    return result;
+  } catch (err) {
+    log.warn({ err, directoryPath }, "Failed to read reference files");
+    return body;
+  }
+}
+
 function loadSkillDefinition(skill: SkillSummary): SkillLookupResult {
   let loaded: SkillDefinition | null;
   if (skill.bundled) {
@@ -992,6 +1144,10 @@ function loadSkillDefinition(skill: SkillSummary): SkillLookupResult {
   }
   // Replace {baseDir} placeholders with the actual skill directory path
   loaded.body = loaded.body.replaceAll("{baseDir}", loaded.directoryPath);
+  // Strip feature-gated sections based on assistant feature flags
+  loaded.body = applyFeatureGatedSections(loaded.body);
+  // Auto-load reference files from references/ subdirectory
+  loaded.body = appendReferenceFiles(loaded.body, loaded.directoryPath);
   return { skill: loaded };
 }
 
@@ -1020,7 +1176,9 @@ export function resolveSkillSelector(
   }
 
   const exactNameMatches = catalog.filter(
-    (skill) => skill.name.toLowerCase() === needle.toLowerCase(),
+    (skill) =>
+      skill.name.toLowerCase() === needle.toLowerCase() ||
+      skill.displayName.toLowerCase() === needle.toLowerCase(),
   );
   if (exactNameMatches.length === 1) {
     return { skill: exactNameMatches[0] };

package/src/config/types.ts

@@ -34,29 +34,10 @@ export type {
   SkillsConfig,
   SkillsInstallConfig,
   SkillsLoadConfig,
-  SmsConfig,
+  SlackConfig,
   SwarmConfig,
   ThinkingConfig,
   TimeoutConfig,
   UiConfig,
   WorkspaceGitConfig,
 } from "./schema.js";
-
-/**
- * Legacy feature flags section (Record<string, boolean>).
- * Uses the key format `skills.<skillId>.enabled`.
- * Missing key defaults to `true` (enabled); explicit `false` only applies when
- * the corresponding canonical key is declared in the defaults registry.
- *
- * @deprecated Prefer `assistantFeatureFlagValues` with canonical key format
- * `feature_flags.<id>.enabled`. This section is kept for backward compatibility
- * and is still consulted by the resolver as a fallback.
- */
-export type FeatureFlags = Record<string, boolean>;
-
-/**
- * Assistant feature flag values using the canonical key format
- * `feature_flags.<id>.enabled`. Takes priority over the legacy
- * `featureFlags` section during resolution, for declared keys.
- */
-export type AssistantFeatureFlagValues = Record<string, boolean>;

package/src/contacts/contact-store.ts

@@ -91,8 +91,6 @@ interface SyncChannelData {
   isPrimary?: boolean;
   externalUserId?: string | null;
   externalChatId?: string | null;
-  /** Raw (pre-canonicalization) address used for dedup fallback when matching contacts created before address normalization. */
-  legacyAddress?: string;
   status?: ChannelStatus;
   policy?: ChannelPolicy;
   verifiedAt?: number | null;
@@ -185,7 +183,7 @@ export function upsertContact(params: {
   if (!contactId && params.channels && params.channels.length > 0) {
     for (const ch of params.channels) {
       // Primary lookup: match by (type, address)
-      let existingChannel = db
+      const existingChannel = db
         .select()
         .from(contactChannels)
         .where(
@@ -196,27 +194,6 @@ export function upsertContact(params: {
         )
         .get();
 
-      // Fallback: if the address was canonicalized, the old record may still
-      // have the raw (non-canonical) address stored. Try matching by
-      // legacyAddress so we update the existing contact instead of creating
-      // a duplicate.
-      if (
-        !existingChannel &&
-        ch.legacyAddress &&
-        ch.legacyAddress.toLowerCase() !== ch.address.toLowerCase()
-      ) {
-        existingChannel = db
-          .select()
-          .from(contactChannels)
-          .where(
-            and(
-              eq(contactChannels.type, ch.type),
-              eq(contactChannels.address, ch.legacyAddress.toLowerCase()),
-            ),
-          )
-          .get();
-      }
-
       if (existingChannel) {
         contactId = existingChannel.contactId;
         const updateSet: Record<string, unknown> = {
@@ -283,7 +260,7 @@ function syncChannels(
     const normalizedAddress = ch.address.toLowerCase();
 
     // Check if this channel already exists for this contact
-    let existing = db
+    const existing = db
       .select()
       .from(contactChannels)
       .where(
@@ -295,31 +272,8 @@ function syncChannels(
       )
       .get();
 
-    // Fallback: the channel may have been stored with a pre-canonicalization
-    // address. Try matching by legacyAddress to find it.
-    if (
-      !existing &&
-      ch.legacyAddress &&
-      ch.legacyAddress.toLowerCase() !== normalizedAddress
-    ) {
-      existing = db
-        .select()
-        .from(contactChannels)
-        .where(
-          and(
-            eq(contactChannels.contactId, contactId),
-            eq(contactChannels.type, ch.type),
-            eq(contactChannels.address, ch.legacyAddress.toLowerCase()),
-          ),
-        )
-        .get();
-    }
-
     if (existing) {
       const updateSet: Record<string, unknown> = {};
-      // Migrate address to canonical form if it changed
-      if (existing.address !== normalizedAddress)
-        updateSet.address = normalizedAddress;
       if (ch.isPrimary !== undefined) updateSet.isPrimary = ch.isPrimary;
       if (ch.externalUserId !== undefined)
         updateSet.externalUserId = ch.externalUserId;
@@ -416,6 +370,12 @@ export function searchContacts(params: {
     const contactIds = [...new Set(channelRows.map((r) => r.contactId))];
     if (contactIds.length === 0) return [];
 
+    // Pre-compute the sanitized query for display-name filtering so the
+    // loop body stays cheap.
+    const sanitizedQuery = params.query
+      ? escapeLike(params.query).toLowerCase()
+      : undefined;
+
     const results: ContactWithChannels[] = [];
     for (const id of contactIds) {
       if (results.length >= limit) break;
@@ -423,7 +383,10 @@ export function searchContacts(params: {
       if (
         contact &&
         (!params.role || contact.role === params.role) &&
-        (!params.contactType || contact.contactType === params.contactType)
+        (!params.contactType || contact.contactType === params.contactType) &&
+        (!sanitizedQuery ||
+          (contact.displayName &&
+            contact.displayName.toLowerCase().includes(sanitizedQuery)))
       ) {
         results.push(contact);
       }

package/src/contacts/contacts-write.ts

@@ -7,7 +7,7 @@
  */
 
 import type { ChannelId } from "../channels/types.js";
-import type { GuardianBinding } from "../memory/channel-guardian-store.js";
+import type { GuardianBinding } from "../memory/channel-verification-sessions.js";
 import { canonicalizeInboundIdentity } from "../util/canonicalize-identity.js";
 import { getLogger } from "../util/logger.js";
 import { emitContactChange } from "./contact-events.js";
@@ -180,10 +180,6 @@ export function upsertContactChannel(params: {
         address,
         externalUserId: canonicalId,
         externalChatId: params.externalChatId ?? null,
-        legacyAddress:
-          params.externalUserId && params.externalUserId !== address
-            ? params.externalUserId
-            : undefined,
         status: (params.status as ChannelStatus) ?? undefined,
         policy: (params.policy as ChannelPolicy) ?? undefined,
         inviteId: params.inviteId ?? null,

package/src/contacts/index.ts

@@ -14,7 +14,5 @@ export type {
   ContactChannel,
   ContactRole,
   ContactWithChannels,
-  MemberPolicy,
-  MemberStatus,
 } from "./types.js";
 export { CHANNEL_TYPES } from "./types.js";

package/src/contacts/types.ts

@@ -54,14 +54,6 @@ export type ChannelStatus =
   | "unverified";
 export type ChannelPolicy = "allow" | "deny" | "escalate";
 
-/**
- * Legacy aliases — semantic names used by API consumers and the ingress
- * pipeline. MemberStatus omits `"unverified"` because the external API maps
- * that value to `"pending"`.
- */
-export type MemberStatus = "pending" | "active" | "revoked" | "blocked";
-export type MemberPolicy = "allow" | "deny" | "escalate";
-
 export interface ContactChannel {
   id: string;
   contactId: string;