@vellumai/assistant 0.5.13 → 0.5.15

package/src/memory/search/mmr.ts

@@ -0,0 +1,136 @@
+import { generateSparseEmbedding } from "../embedding-backend.js";
+import type { SparseEmbedding } from "../embedding-types.js";
+import type { TieredCandidate } from "./tier-classifier.js";
+
+/**
+ * Compute cosine similarity between two sparse vectors.
+ * Returns 0 if either vector has zero magnitude.
+ */
+function sparseCosine(a: SparseEmbedding, b: SparseEmbedding): number {
+  // Build index→value map for vector b
+  const bMap = new Map<number, number>();
+  for (let i = 0; i < b.indices.length; i++) {
+    bMap.set(b.indices[i]!, b.values[i]!);
+  }
+
+  // Compute dot product over shared indices
+  let dotProduct = 0;
+  for (let i = 0; i < a.indices.length; i++) {
+    const bVal = bMap.get(a.indices[i]!);
+    if (bVal !== undefined) {
+      dotProduct += a.values[i]! * bVal;
+    }
+  }
+
+  // Compute magnitudes
+  let magA = 0;
+  for (const v of a.values) magA += v * v;
+  magA = Math.sqrt(magA);
+
+  let magB = 0;
+  for (const v of b.values) magB += v * v;
+  magB = Math.sqrt(magB);
+
+  if (magA === 0 || magB === 0) return 0;
+  return dotProduct / (magA * magB);
+}
+
+/**
+ * Apply Maximal Marginal Relevance (MMR) diversity ranking to candidates.
+ *
+ * Items are re-ranked using a greedy selection loop that progressively
+ * penalizes candidates whose text is similar to already-selected ones.
+ * Non-item candidates (segments, summaries, media) pass through unpenalized
+ * since they represent different conversation windows.
+ *
+ * @param candidates - Scored candidates from upstream ranking
+ * @param penalty - Float 0..1. 0 = no diversity pressure, 1 = maximum
+ * @returns Re-ranked candidates with adjusted finalScores
+ */
+export function applyMMR(
+  candidates: TieredCandidate[],
+  penalty: number,
+): TieredCandidate[] {
+  // Pre-compute sparse embeddings for all candidates
+  const embeddings = candidates.map((c) => generateSparseEmbedding(c.text));
+
+  // Separate items from non-items
+  const items: { index: number; candidate: TieredCandidate }[] = [];
+  const nonItems: TieredCandidate[] = [];
+
+  for (let i = 0; i < candidates.length; i++) {
+    const c = candidates[i]!;
+    if (c.type === "item") {
+      items.push({ index: i, candidate: c });
+    } else {
+      nonItems.push(c);
+    }
+  }
+
+  // If no items or no penalty, pass through in original order
+  if (items.length === 0 || penalty === 0) {
+    return candidates;
+  }
+
+  // Greedy MMR selection loop
+  const selected: number[] = [];
+  const remaining = new Set<number>(items.map((_, i) => i));
+  const adjustedScores = new Map<number, number>();
+
+  // Select the item with the highest finalScore first
+  let bestIdx = -1;
+  let bestScore = -Infinity;
+  for (const idx of remaining) {
+    const score = items[idx]!.candidate.finalScore;
+    if (score > bestScore) {
+      bestScore = score;
+      bestIdx = idx;
+    }
+  }
+  selected.push(bestIdx);
+  remaining.delete(bestIdx);
+  adjustedScores.set(bestIdx, items[bestIdx]!.candidate.finalScore);
+
+  // Iteratively select remaining items
+  while (remaining.size > 0) {
+    let nextBestIdx = -1;
+    let nextBestScore = -Infinity;
+
+    for (const idx of remaining) {
+      const itemEmbIdx = items[idx]!.index;
+
+      // Compute max similarity to any already-selected item
+      let maxSim = 0;
+      for (const selIdx of selected) {
+        const selEmbIdx = items[selIdx]!.index;
+        const sim = sparseCosine(
+          embeddings[itemEmbIdx]!,
+          embeddings[selEmbIdx]!,
+        );
+        if (sim > maxSim) maxSim = sim;
+      }
+
+      const adjustedScore =
+        items[idx]!.candidate.finalScore * (1 - maxSim * penalty);
+      if (adjustedScore > nextBestScore) {
+        nextBestScore = adjustedScore;
+        nextBestIdx = idx;
+      }
+    }
+
+    selected.push(nextBestIdx);
+    remaining.delete(nextBestIdx);
+    adjustedScores.set(nextBestIdx, nextBestScore);
+  }
+
+  // Rebuild output: non-items first (original order), then items in selected order
+  const result: TieredCandidate[] = [...nonItems];
+  for (const idx of selected) {
+    result.push({
+      ...items[idx]!.candidate,
+      finalScore: adjustedScores.get(idx)!,
+    });
+  }
+
+  return result;
+}

package/src/memory/search/staleness.ts

@@ -1,4 +1,3 @@
-import type { TieredCandidate } from "./tier-classifier.js";
 import type { StalenessLevel } from "./types.js";
 
 const BASE_LIFETIME_MS: Record<string, number> = {
@@ -39,17 +38,3 @@ export function computeStaleness(
   if (ratio <= 2) return { level: "stale", ratio };
   return { level: "very_stale", ratio };
 }
-
-/**
- * Demote very_stale tier-1 candidates to tier 2.
- */
-export function applyStaleDemotion(
-  candidates: TieredCandidate[],
-): TieredCandidate[] {
-  return candidates.map((c) => {
-    if (c.tier === 1 && c.staleness === "very_stale") {
-      return { ...c, tier: 2 as const };
-    }
-    return c;
-  });
-}

package/src/memory/search/tier-classifier.ts

@@ -1,29 +1,18 @@
 import type { Candidate } from "./types.js";
 
-export type Tier = 1 | 2;
-
-export interface TieredCandidate extends Candidate {
-  tier: Tier;
+/** Backward-compatible alias — downstream files import this type. */
+export type TieredCandidate = Candidate & {
   /** Human-readable label for the source conversation/summary (e.g. conversation title). */
   sourceLabel?: string;
-}
+};
+
+const MIN_SCORE_THRESHOLD = 0.2;
 
 /**
- * Map a composite relevance score to an injection tier.
- *
- * Thresholds are intentionally set lower than raw-embedding ceilings because
- * the multiplicative scoring pipeline (semantic × recency × metadata) compresses
- * the effective score range.  Lowering the gates lets moderately-relevant items
- * surface rather than being silently dropped.
+ * Filter candidates to those exceeding the minimum relevance threshold.
+ * Replaces the former tier 1/tier 2 classification — all surviving candidates
+ * are treated equally and ranked by score.
  */
-export function classifyTier(score: number): Tier | null {
-  if (score > 0.6) return 1;
-  if (score > 0.4) return 2;
-  return null;
-}
-
-export function classifyTiers(candidates: Candidate[]): TieredCandidate[] {
-  return candidates
-    .map((c) => ({ ...c, tier: classifyTier(c.finalScore) }))
-    .filter((c): c is TieredCandidate => c.tier != null);
+export function filterByMinScore(candidates: Candidate[]): TieredCandidate[] {
+  return candidates.filter((c) => c.finalScore > MIN_SCORE_THRESHOLD);
 }

package/src/memory/search/types.ts

@@ -15,6 +15,10 @@ export interface Candidate {
   conversationId?: string;
   /** The source message ID this candidate was extracted from (segments only). */
   messageId?: string;
+  /** The ID of the memory item this candidate supersedes (items only). */
+  supersedes?: string;
+  /** Relative workspace path to the source conversation's messages file. */
+  sourcePath?: string;
   confidence: number;
   importance: number;
   createdAt: number;
@@ -32,6 +36,7 @@ export interface MemoryRecallCandiateDebug {
   finalScore: number;
   semantic: number;
   recency: number;
+  sourceLabel?: string;
 }
 
 export type DegradationReason =
@@ -67,6 +72,12 @@ export interface MemoryRecallResult {
   hybridSearchMs?: number;
   /** Whether sparse vectors were used in the hybrid search. */
   sparseVectorUsed?: boolean;
+  /** Whether HyDE query expansion was used for this retrieval. */
+  hydeExpanded?: boolean;
+  /** Number of hypothetical documents generated by HyDE expansion. */
+  hydeDocCount?: number;
+  /** Whether MMR diversity ranking was applied to candidates. */
+  mmrApplied?: boolean;
 }
 
 /**
@@ -94,6 +105,12 @@ export interface MemoryRecallOptions {
    */
   scopePolicyOverride?: ScopePolicyOverride;
   maxInjectTokensOverride?: number;
+  /**
+   * When true, use HyDE (Hypothetical Document Embeddings) query expansion
+   * to generate hypothetical memory documents, embed them alongside the raw
+   * query, and run parallel semantic searches for improved recall.
+   */
+  hydeEnabled?: boolean;
 }
 
 export interface ItemMetadata {

package/src/messaging/providers/slack/adapter.ts

@@ -5,6 +5,8 @@
  * implements the MessagingProvider interface.
  */
 
+import { findContactChannel } from "../../../contacts/contact-store.js";
+import { upsertContactChannel } from "../../../contacts/contacts-write.js";
 import type { OAuthConnection } from "../../../oauth/connection.js";
 import { resolveOAuthConnection } from "../../../oauth/connection-resolver.js";
 import { isProviderConnected } from "../../../oauth/oauth-store.js";
@@ -62,6 +64,21 @@ async function resolveUserName(
   const cached = userNameCache.get(userId);
   if (cached) return cached;
 
+  // Check contacts DB for a persistent cache hit
+  try {
+    const result = findContactChannel({
+      channelType: "slack",
+      externalUserId: userId,
+    });
+    if (result) {
+      const name = result.contact.displayName;
+      userNameCache.set(userId, name);
+      return name;
+    }
+  } catch {
+    // Contact lookup failures are non-fatal — fall through to API
+  }
+
   try {
     const resp = await slack.userInfo(auth, userId);
     const name =
@@ -70,6 +87,18 @@ async function resolveUserName(
       resp.user.real_name ||
       resp.user.name;
     userNameCache.set(userId, name);
+
+    // Persist to contacts for future sessions
+    try {
+      upsertContactChannel({
+        sourceChannel: "slack",
+        externalUserId: userId,
+        displayName: name,
+      });
+    } catch {
+      // Non-fatal — caching failure shouldn't break messaging
+    }
+
     return name;
   } catch {
     return userId;
@@ -216,13 +245,30 @@ export const slackProvider: MessagingProvider = {
       (!options?.limit || conversations.length < options.limit)
     );
 
-    // Resolve DM user names
+    // Resolve DM user names and cache channel mappings
     for (const conv of conversations) {
       if (conv.type === "dm" && conv.metadata?.dmUserId) {
-        conv.name = await resolveUserName(
-          auth,
-          conv.metadata.dmUserId as string,
-        );
+        const dmUserId = conv.metadata.dmUserId as string;
+        conv.name = await resolveUserName(auth, dmUserId);
+
+        // Persist the DM channel ID so future sends skip conversations.open
+        try {
+          const existing = findContactChannel({
+            channelType: "slack",
+            externalUserId: dmUserId,
+          });
+          if (existing && !existing.channel.externalChatId) {
+            upsertContactChannel({
+              contactId: existing.contact.id,
+              sourceChannel: "slack",
+              externalUserId: dmUserId,
+              externalChatId: conv.id,
+              displayName: conv.name,
+            });
+          }
+        } catch {
+          // Non-fatal
+        }
       }
     }
 

package/src/notifications/broadcaster.ts

@@ -147,6 +147,19 @@ export class NotificationBroadcaster {
         };
       }
 
+      // For tool_grant_request signals, prefer the deterministic template seed
+      // over LLM-generated prose. The enriched questionText is already concise
+      // and informative — LLM rewording just adds noise.
+      if (signal.contextPayload?.requestKind === "tool_grant_request") {
+        if (!fallbackCopy) {
+          fallbackCopy = composeFallbackCopy(signal, decision.selectedChannels);
+        }
+        const templateSeed = fallbackCopy[channel]?.conversationSeedMessage;
+        if (templateSeed) {
+          copy = { ...copy, conversationSeedMessage: templateSeed };
+        }
+      }
+
       // Resolve the per-channel conversation action from the decision (default: start_new)
       const conversationAction: ConversationAction | undefined =
         decision.conversationActions?.[channel];

package/src/notifications/copy-composer.ts

@@ -326,10 +326,17 @@ const TEMPLATES: Partial<Record<NotificationSourceEventName, CopyTemplate>> = {
     const requestCode = nonEmpty(
       typeof payload.requestCode === "string" ? payload.requestCode : undefined,
     );
+
+    // For tool_grant_request, the questionText already includes requester name + input summary.
+    // Use it directly as the conversation seed to avoid LLM-generated filler.
+    const isToolGrant = payload.requestKind === "tool_grant_request";
+    const conversationSeedMessage = isToolGrant ? question : undefined;
+
     if (!requestCode) {
       return {
         title: "Guardian Question",
         body: question,
+        conversationSeedMessage,
       };
     }
 
@@ -342,6 +349,7 @@ const TEMPLATES: Partial<Record<NotificationSourceEventName, CopyTemplate>> = {
     return {
       title: "Guardian Question",
       body: `${question}\n\n${instruction}`,
+      conversationSeedMessage,
     };
   },
 

package/src/oauth/connect-orchestrator.ts

@@ -229,7 +229,7 @@ export async function orchestrateOAuthConnect(
           return {
             success: false,
             error:
-              "oauth2_connect from a non-interactive session requires a public ingress URL. Configure ingress.publicBaseUrl first.",
+              "OAuth connect from a non-interactive session requires a public ingress URL. Configure ingress.publicBaseUrl first.",
             safeError: true,
           };
         }

package/src/oauth/connection-resolver.ts

@@ -88,7 +88,7 @@ export async function resolveOAuthConnection(
       ? ` matching ${filters.join(" and ")}`
       : "";
     throw new Error(
-      `No active OAuth connection found for "${providerKey}"${qualifier}. Connect the service first with oauth2_connect.`,
+      `No active OAuth connection found for "${providerKey}"${qualifier}. Connect the service first with \`assistant oauth connect ${providerKey}\`.`,
     );
   }
 
@@ -97,7 +97,7 @@ export async function resolveOAuthConnection(
   );
   if (!accessToken) {
     throw new Error(
-      `OAuth connection for "${providerKey}" exists but has no access token. Re-authorize with oauth2_connect.`,
+      `OAuth connection for "${providerKey}" exists but has no access token. Re-authorize with \`assistant oauth connect ${providerKey}\`.`,
     );
   }
 

package/src/oauth/provider-serializer.ts

@@ -0,0 +1,116 @@
+/**
+ * Shared serialization utilities for OAuth provider rows.
+ *
+ * Used by both the CLI (providers commands) and runtime API endpoints to
+ * produce consistent, parsed representations of provider rows stored in
+ * the database.
+ */
+
+import type { OAuthProviderRow } from "./oauth-store.js";
+
+/**
+ * Full serialized representation of an OAuth provider row.
+ *
+ * JSON string fields are parsed into their native types, boolean/integer
+ * fields are normalised to booleans, timestamps are ISO 8601 strings,
+ * and a computed `supportsManagedMode` flag is included.
+ */
+export type SerializedProvider = ReturnType<typeof serializeProvider> &
+  Record<string, unknown>;
+
+/**
+ * Lightweight summary projection of an OAuth provider, suitable for API
+ * list responses where full detail is not needed. All keys are snake_case
+ * to match the HTTP API convention.
+ */
+export interface SerializedProviderSummary {
+  provider_key: string;
+  display_name: string | null;
+  description: string | null;
+  dashboard_url: string | null;
+  client_id_placeholder: string | null;
+  requires_client_secret: boolean;
+  supports_managed_mode: boolean;
+}
+
+/**
+ * Serialize a full provider row from the database into a parsed object.
+ *
+ * JSON string columns are parsed, boolean/integer fields are normalised to
+ * booleans, and timestamps are converted to ISO 8601 strings. An optional
+ * `redirectUri` override can be supplied by the caller (e.g. the CLI,
+ * which resolves the redirect URI from config).
+ *
+ * Returns `undefined` when `row` is `undefined`, and `null` when `row` is
+ * `null`, preserving the caller's nullable semantics.
+ */
+export function serializeProvider(
+  row: OAuthProviderRow | null | undefined,
+  options?: { redirectUri?: string | null },
+): ReturnType<typeof _serializeProvider> | null | undefined {
+  if (row === undefined) return undefined;
+  if (row === null) return null;
+  return _serializeProvider(row, options);
+}
+
+function _serializeProvider(
+  row: OAuthProviderRow,
+  options?: { redirectUri?: string | null },
+) {
+  return {
+    ...row,
+    displayName: row.displayName ?? null,
+    description: row.description ?? null,
+    dashboardUrl: row.dashboardUrl ?? null,
+    clientIdPlaceholder: row.clientIdPlaceholder ?? null,
+    requiresClientSecret: !!(row.requiresClientSecret ?? 1),
+    supportsManagedMode: !!row.managedServiceConfigKey,
+    defaultScopes: row.defaultScopes ? JSON.parse(row.defaultScopes) : [],
+    scopePolicy: row.scopePolicy ? JSON.parse(row.scopePolicy) : {},
+    extraParams: row.extraParams ? JSON.parse(row.extraParams) : null,
+    pingHeaders: row.pingHeaders ? JSON.parse(row.pingHeaders) : null,
+    pingBody: row.pingBody ? JSON.parse(row.pingBody) : null,
+    loopbackPort: row.loopbackPort ?? null,
+    injectionTemplates: row.injectionTemplates
+      ? JSON.parse(row.injectionTemplates)
+      : null,
+    appType: row.appType ?? null,
+    setupNotes: row.setupNotes ? JSON.parse(row.setupNotes) : null,
+    identityUrl: row.identityUrl ?? null,
+    identityMethod: row.identityMethod ?? null,
+    identityHeaders: row.identityHeaders
+      ? JSON.parse(row.identityHeaders)
+      : null,
+    identityBody: row.identityBody ? JSON.parse(row.identityBody) : null,
+    identityResponsePaths: row.identityResponsePaths
+      ? JSON.parse(row.identityResponsePaths)
+      : null,
+    identityFormat: row.identityFormat ?? null,
+    identityOkField: row.identityOkField ?? null,
+    redirectUri:
+      options?.redirectUri !== undefined ? options.redirectUri : null,
+    createdAt: new Date(row.createdAt).toISOString(),
+    updatedAt: new Date(row.updatedAt).toISOString(),
+  };
+}
+
+/**
+ * Return a lightweight snake_case summary of a provider row, suitable for
+ * embedding in API list responses.
+ *
+ * Returns `null` when `row` is nullish.
+ */
+export function serializeProviderSummary(
+  row: OAuthProviderRow | null | undefined,
+): SerializedProviderSummary | null {
+  if (!row) return null;
+  return {
+    provider_key: row.providerKey,
+    display_name: row.displayName ?? null,
+    description: row.description ?? null,
+    dashboard_url: row.dashboardUrl ?? null,
+    client_id_placeholder: row.clientIdPlaceholder ?? null,
+    requires_client_secret: !!(row.requiresClientSecret ?? 1),
+    supports_managed_mode: !!row.managedServiceConfigKey,
+  };
+}

package/src/permissions/trust-store.ts

@@ -6,6 +6,7 @@ import {
   renameSync,
   writeFileSync,
 } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
 import { Minimatch } from "minimatch";
@@ -13,7 +14,6 @@ import { v4 as uuid } from "uuid";
 
 import { getIsContainerized } from "../config/env-registry.js";
 import { getLogger } from "../util/logger.js";
-import { getRootDir } from "../util/platform.js";
 import { getDefaultRuleTemplates } from "./defaults.js";
 import * as trustClient from "./trust-client.js";
 import type {
@@ -128,7 +128,19 @@ function rebuildPatternCache(rules: TrustRule[]): void {
 }
 
 function getTrustPath(): string {
-  return join(getRootDir(), "protected", "trust.json");
+  return join(getGatewaySecurityDir(), "trust.json");
+}
+
+/**
+ * Resolve the gateway security directory.
+ *
+ * Docker: `GATEWAY_SECURITY_DIR` env var.
+ * Local:  falls back to `~/.vellum/` + `protected/`.
+ */
+function getGatewaySecurityDir(): string {
+  const securityDir = process.env.GATEWAY_SECURITY_DIR;
+  if (securityDir) return securityDir;
+  return join(homedir(), ".vellum", "protected");
 }
 
 /**
@@ -1103,11 +1115,9 @@ function getGatewayTrustStore(): GatewayTrustStoreAdapter {
  * Returns the active trust store backend.
  *
  * When `IS_CONTAINERIZED=true`, returns a gateway-backed adapter that
- * proxies all trust operations through the gateway HTTP API. The daemon
- * never reads or writes `protected/trust.json` directly in Docker.
+ * proxies all trust operations through the gateway HTTP API.
  *
- * When `IS_CONTAINERIZED=false`, returns the file-based implementation
- * (no change from previous behavior).
+ * When `IS_CONTAINERIZED=false`, returns the file-based implementation.
  */
 export function getTrustStore(): TrustStoreBackend {
   if (getIsContainerized()) {
@@ -1133,7 +1143,14 @@ export function addRule(
     executionTarget?: string;
   },
 ): TrustRule {
-  return getTrustStore().addRule(tool, pattern, scope, decision, priority, options);
+  return getTrustStore().addRule(
+    tool,
+    pattern,
+    scope,
+    decision,
+    priority,
+    options,
+  );
 }
 
 export function updateRule(

package/src/prompts/__tests__/build-cli-reference-section.test.ts

@@ -23,6 +23,11 @@ describe("buildCliReferenceSection", () => {
     expect(result).toContain("assistant --help");
   });
 
+  test("mentions assistant platform for querying platform state", () => {
+    const result = buildCliReferenceSection();
+    expect(result).toContain("assistant platform status");
+  });
+
   test("does not embed the full CLI help output", () => {
     const result = buildCliReferenceSection();
     // The full help text used to be embedded; now the model should