@vellumai/assistant 0.4.49 → 0.4.50

package/src/tools/memory/handlers.test.ts

@@ -55,6 +55,7 @@ mock.module("../../memory/embedding-local.js", () => ({
 mock.module("../../memory/qdrant-client.js", () => ({
   getQdrantClient: () => ({
     searchWithFilter: async () => [],
+    hybridSearch: async () => [],
     upsertPoints: async () => {},
     deletePoints: async () => {},
   }),
@@ -93,14 +94,14 @@ import {
   memoryItemSources,
   messages,
 } from "../../memory/schema.js";
-import { handleMemoryRecall, type MemoryRecallToolResult } from "./handlers.js";
+import type { MemoryRecallToolResult } from "./handlers.js";
+import { handleMemoryRecall } from "./handlers.js";
 
 function clearTables() {
   const db = getDb();
   db.run("DELETE FROM memory_item_sources");
   db.run("DELETE FROM memory_items");
   db.run("DELETE FROM memory_segments");
-  db.run("DELETE FROM memory_segment_fts");
   db.run("DELETE FROM messages");
   db.run("DELETE FROM conversations");
 }
@@ -237,7 +238,7 @@ function seedMemory() {
 
   insertItem(db, {
     id: "item-testing",
-    kind: "fact",
+    kind: "identity",
     subject: "testing",
     statement: "The project uses bun test for unit testing",
     firstSeenAt: now - 20_000,
@@ -284,7 +285,7 @@ describe("handleMemoryRecall", () => {
 
   // ── Happy path ────────────────────────────────────────────────────
 
-  test("returns formatted results from multiple sources", async () => {
+  test("returns valid result shape with Qdrant mocked empty", async () => {
     seedMemory();
 
     const result = await handleMemoryRecall(
@@ -292,35 +293,13 @@ describe("handleMemoryRecall", () => {
       TEST_CONFIG,
     );
 
+    // With Qdrant mocked empty, hybrid search returns nothing.
+    // Recency search also returns nothing (no conversationId passed to handler).
+    // The handler should return a valid result shape with zero results.
     expect(result.isError).toBe(false);
     const parsed = parseResult(result.content);
-    expect(parsed.resultCount).toBeGreaterThan(0);
-    expect(parsed.text.length).toBeGreaterThan(0);
-  });
-
-  test("respects max_results parameter", async () => {
-    seedMemory();
-
-    const result = await handleMemoryRecall(
-      { query: "API design", max_results: 1 },
-      TEST_CONFIG,
-    );
-
-    expect(result.isError).toBe(false);
-    const parsed = parseResult(result.content);
-    expect(parsed.resultCount).toBeLessThanOrEqual(1);
-  });
-
-  test("clamps max_results to 50", async () => {
-    seedMemory();
-
-    // Should not throw, max_results capped at 50
-    const result = await handleMemoryRecall(
-      { query: "API design", max_results: 100 },
-      TEST_CONFIG,
-    );
-
-    expect(result.isError).toBe(false);
+    expect(typeof parsed.resultCount).toBe("number");
+    expect(typeof parsed.text).toBe("string");
   });
 
   // ── Empty results ─────────────────────────────────────────────────
@@ -336,10 +315,8 @@ describe("handleMemoryRecall", () => {
     const parsed = parseResult(result.content);
     expect(parsed.resultCount).toBe(0);
     expect(parsed.text).toBe("No matching memories found.");
-    expect(parsed.sources.lexical).toBe(0);
     expect(parsed.sources.semantic).toBe(0);
     expect(parsed.sources.recency).toBe(0);
-    expect(parsed.sources.entity).toBe(0);
   });
 
   // ── Degraded mode ─────────────────────────────────────────────────
@@ -399,11 +376,13 @@ describe("handleMemoryRecall", () => {
     // Not degraded because embeddings are optional
     expect(parsed.degraded).toBe(false);
     expect(parsed.sources.semantic).toBe(0);
-    // Still returns results from non-semantic sources (direct item search)
-    expect(parsed.resultCount).toBeGreaterThan(0);
+    // With FTS/direct-item search removed, only Qdrant hybrid search and
+    // recency search remain. Both return empty here (Qdrant mocked,
+    // no conversationId passed). The handler returns a valid empty result.
+    expect(parsed.resultCount).toBe(0);
   });
 
-  test("returns lexical results in degraded mode", async () => {
+  test("gracefully returns empty in degraded mode without embeddings", async () => {
     seedMemory();
 
     const degradedConfig: AssistantConfig = {
@@ -425,70 +404,76 @@ describe("handleMemoryRecall", () => {
 
     expect(result.isError).toBe(false);
     const parsed = parseResult(result.content);
-    // Direct item search should still find items even without embeddings
-    expect(parsed.resultCount).toBeGreaterThan(0);
+    // With FTS removed and Qdrant mocked, no retrieval path finds items.
+    // The handler returns a valid empty result without throwing.
+    expect(typeof parsed.resultCount).toBe("number");
   });
 
   // ── Scope filtering ───────────────────────────────────────────────
 
-  test("scope 'conversation' restricts to current thread", async () => {
+  test("scope 'conversation' passes scope policy override to retriever", async () => {
+    // Seed a conversation with segments in the target scope and in a different
+    // scope. With scope="conversation", only the target scope's segments should
+    // be returned (fallbackToDefault=false).
     const db = getDb();
     const now = Date.now();
+    const convId = "conv-scope-a";
+
+    insertConversation(db, convId, now - 10_000);
+    insertMessage(
+      db,
+      "msg-scope-a",
+      convId,
+      "user",
+      "scoped data for conversation A",
+      now - 5_000,
+    );
 
-    // Insert item in "conv-scope-a" scope
-    insertItem(db, {
-      id: "item-scope-a",
-      kind: "fact",
-      subject: "scoped data",
-      statement: "This item is scoped to conversation A",
-      firstSeenAt: now - 10_000,
-      scopeId: "conv-scope-a",
-    });
+    // Insert a segment scoped to this conversation's scope
+    db.run(`
+      INSERT INTO memory_segments (id, message_id, conversation_id, role, segment_index, text, token_estimate, scope_id, created_at, updated_at)
+      VALUES ('seg-scope-a', 'msg-scope-a', '${convId}', 'user', 0, 'Conversation-scoped data for conversation A', 8, '${convId}', ${
+        now - 5_000
+      }, ${now - 5_000})
+    `);
+
+    // Insert an out-of-scope segment that should NOT be returned
+    db.run(`
+      INSERT INTO memory_segments (id, message_id, conversation_id, role, segment_index, text, token_estimate, scope_id, created_at, updated_at)
+      VALUES ('seg-scope-other', 'msg-scope-a', '${convId}', 'user', 1, 'Out-of-scope data from a different scope', 8, 'other-scope', ${
+        now - 5_000
+      }, ${now - 5_000})
+    `);
 
-    // Insert item in default scope
-    insertItem(db, {
-      id: "item-default",
-      kind: "fact",
-      subject: "default data",
-      statement: "This item is in the default scope about scoped data",
-      firstSeenAt: now - 10_000,
-      scopeId: "default",
-    });
-
-    // Query with scope="conversation" and scopeId="conv-scope-a"
-    // should restrict to only that scope (no fallback to default)
     const result = await handleMemoryRecall(
-      { query: "scoped data", scope: "conversation" },
+      { query: "data", scope: "conversation" },
       TEST_CONFIG,
-      "conv-scope-a",
+      convId,
+      convId,
     );
 
     expect(result.isError).toBe(false);
     const parsed = parseResult(result.content);
-
-    // When scope is "conversation", fallbackToDefault is false,
-    // so only items from conv-scope-a should appear
-    expect(parsed.resultCount).toBeGreaterThan(0);
-    expect(parsed.text).toContain("scoped to conversation A");
-    expect(parsed.text).not.toContain("default scope");
+    // With conversation scope, only the conversation-scoped segment is returned.
+    // The other-scope segment should be excluded (fallbackToDefault=false).
+    expect(parsed.sources.recency).toBe(1);
+    expect(parsed.text).toContain("Conversation-scoped data");
+    expect(parsed.text).not.toContain("Out-of-scope data");
   });
 
-  test("default scope includes fallback to default scope", async () => {
+  test("default scope handler invocation does not error", async () => {
     const db = getDb();
     const now = Date.now();
 
-    // Insert item in default scope
     insertItem(db, {
       id: "item-fallback",
-      kind: "fact",
+      kind: "identity",
       subject: "global knowledge",
       statement: "This global knowledge should be accessible from any scope",
       firstSeenAt: now - 10_000,
       scopeId: "default",
     });
 
-    // Query with scope="default" (the default) and a specific scopeId
-    // should include fallback to default scope
     const result = await handleMemoryRecall(
       { query: "global knowledge" },
       TEST_CONFIG,
@@ -497,37 +482,36 @@ describe("handleMemoryRecall", () => {
 
     expect(result.isError).toBe(false);
     const parsed = parseResult(result.content);
-    // Default scope items should be accessible
-    expect(parsed.resultCount).toBeGreaterThan(0);
-    expect(parsed.text).toContain("global knowledge");
+    // With Qdrant mocked and no conversation segments, the retriever returns
+    // empty. Handler should still return a valid result shape.
+    expect(typeof parsed.resultCount).toBe("number");
   });
 
   // ── Error handling ────────────────────────────────────────────────
 
   test("retrieval failure returns error message, does not throw", async () => {
-    // Create a config that will cause the retrieval pipeline to throw
-    // by making memory disabled in a way that collectAndMergeCandidates breaks.
-    // We mock the retriever to throw an error.
-    const badConfig: AssistantConfig = {
-      ...TEST_CONFIG,
-      memory: {
-        ...TEST_CONFIG.memory,
-        // Force retrieval with impossible settings to trigger an error path
-        retrieval: {
-          ...TEST_CONFIG.memory.retrieval,
-          lexicalTopK: -1, // may cause issues in search
-        },
-      },
-    };
-
-    // Even if the query fails internally, the handler should catch and return
-    // an error result rather than throwing
-    const result = await handleMemoryRecall({ query: "test query" }, badConfig);
-
-    // The function should either succeed gracefully or return an error
-    // but never throw
-    expect(typeof result.content).toBe("string");
-    expect(typeof result.isError).toBe("boolean");
+    // Mock buildMemoryRecall to throw, simulating an internal retrieval failure
+    const retrieverModule = await import("../../memory/retriever.js");
+    const original = retrieverModule.buildMemoryRecall;
+    (retrieverModule as Record<string, unknown>).buildMemoryRecall =
+      async () => {
+        throw new Error("Simulated retrieval failure");
+      };
+
+    try {
+      const result = await handleMemoryRecall(
+        { query: "test query" },
+        TEST_CONFIG,
+      );
+
+      // The handler should catch the error and return an error result,
+      // never throw
+      expect(result.isError).toBe(true);
+      expect(result.content).toContain("Simulated retrieval failure");
+    } finally {
+      // Restore original implementation
+      (retrieverModule as Record<string, unknown>).buildMemoryRecall = original;
+    }
   });
 
   test("result shape matches MemoryRecallToolResult when successful", async () => {
@@ -546,10 +530,8 @@ describe("handleMemoryRecall", () => {
     expect(typeof parsed.resultCount).toBe("number");
     expect(typeof parsed.degraded).toBe("boolean");
     expect(typeof parsed.sources).toBe("object");
-    expect(typeof parsed.sources.lexical).toBe("number");
     expect(typeof parsed.sources.semantic).toBe("number");
     expect(typeof parsed.sources.recency).toBe("number");
-    expect(typeof parsed.sources.entity).toBe("number");
   });
 
   test("empty result shape matches MemoryRecallToolResult", async () => {
@@ -564,9 +546,7 @@ describe("handleMemoryRecall", () => {
     expect(parsed.text).toBe("No matching memories found.");
     expect(parsed.resultCount).toBe(0);
     expect(typeof parsed.degraded).toBe("boolean");
-    expect(parsed.sources.lexical).toBe(0);
     expect(parsed.sources.semantic).toBe(0);
     expect(parsed.sources.recency).toBe(0);
-    expect(parsed.sources.entity).toBe(0);
   });
 });

package/src/tools/memory/handlers.ts

@@ -3,17 +3,9 @@ import { v4 as uuid } from "uuid";
 
 import type { AssistantConfig } from "../../config/types.js";
 import { getDb } from "../../memory/db.js";
-import {
-  getMemoryBackendStatus,
-  logMemoryEmbeddingWarning,
-} from "../../memory/embedding-backend.js";
 import { computeMemoryFingerprint } from "../../memory/fingerprint.js";
-import { formatRecallText } from "../../memory/format-recall.js";
 import { enqueueMemoryJob } from "../../memory/jobs-store.js";
-import {
-  collectAndMergeCandidates,
-  embedWithRetry,
-} from "../../memory/retriever.js";
+import { buildMemoryRecall } from "../../memory/retriever.js";
 import { memoryItems } from "../../memory/schema.js";
 import type { ScopePolicyOverride } from "../../memory/search/types.js";
 import { getLogger } from "../../util/logger.js";
@@ -39,21 +31,37 @@ export async function handleMemorySave(
     };
   }
 
-  const kind = args.kind;
+  const rawKind = args.kind;
   const validKinds = new Set([
+    "identity",
     "preference",
-    "fact",
+    "project",
     "decision",
-    "profile",
-    "relationship",
+    "constraint",
     "event",
-    "opinion",
-    "instruction",
-    "style",
-    "playbook",
-    "learning",
   ]);
-  if (typeof kind !== "string" || !validKinds.has(kind)) {
+  /** Maps old kind names to their new equivalents for backwards compat. */
+  const kindMigrationMap: Record<string, string> = {
+    profile: "identity",
+    fact: "identity",
+    relationship: "identity",
+    opinion: "preference",
+    todo: "project",
+    instruction: "constraint",
+    style: "preference",
+    playbook: "constraint",
+    learning: "identity",
+  };
+  if (typeof rawKind !== "string") {
+    return {
+      content: `Error: kind is required and must be one of: ${[
+        ...validKinds,
+      ].join(", ")}`,
+      isError: true,
+    };
+  }
+  const kind = kindMigrationMap[rawKind] ?? rawKind;
+  if (!validKinds.has(kind)) {
     return {
       content: `Error: kind is required and must be one of: ${[
         ...validKinds,
@@ -255,10 +263,8 @@ export interface MemoryRecallToolResult {
   degraded: boolean;
   items: Array<{ id: string; type: string; kind: string }>;
   sources: {
-    lexical: number;
     semantic: number;
     recency: number;
-    entity: number;
   };
 }
 
@@ -276,11 +282,6 @@ export async function handleMemoryRecall(
     };
   }
 
-  const maxResults =
-    typeof args.max_results === "number" && args.max_results > 0
-      ? Math.min(args.max_results, 50)
-      : 10;
-
   const scope =
     typeof args.scope === "string" && args.scope.trim().length > 0
       ? args.scope.trim()
@@ -298,54 +299,28 @@ export async function handleMemoryRecall(
   try {
     const trimmedQuery = query.trim();
 
-    // Generate embedding vector (graceful degradation if unavailable)
-    let queryVector: number[] | null = null;
-    let provider: string | undefined;
-    let model: string | undefined;
-    let degraded = false;
-
-    const backendStatus = getMemoryBackendStatus(config);
-    if (backendStatus.provider) {
-      try {
-        const embedded = await embedWithRetry(config, [trimmedQuery]);
-        queryVector = embedded.vectors[0] ?? null;
-        provider = embedded.provider;
-        model = embedded.model;
-      } catch (err) {
-        logMemoryEmbeddingWarning(err, "query");
-        degraded = !!config.memory.embeddings.required;
-      }
-    } else {
-      degraded = backendStatus.degraded;
-    }
-
-    // Run the full retrieval pipeline with all sources enabled
-    const collected = await collectAndMergeCandidates(trimmedQuery, config, {
-      queryVector,
-      provider,
-      model,
-      conversationId,
-      scopeId,
-      scopePolicyOverride,
-    });
-
-    if (collected.semanticSearchFailed || collected.semanticUnavailable) {
-      degraded = true;
-    }
+    // Use the unified recall pipeline
+    const recall = await buildMemoryRecall(
+      trimmedQuery,
+      conversationId ?? "",
+      config,
+      {
+        scopeId,
+        scopePolicyOverride,
+      },
+    );
 
-    const candidates = collected.merged.slice(0, maxResults);
+    const degraded = recall.degraded;
 
-    if (candidates.length === 0) {
+    if (recall.selectedCount === 0 || recall.injectedText.length === 0) {
       const result: MemoryRecallToolResult = {
         text: "No matching memories found.",
         resultCount: 0,
         degraded,
         items: [],
         sources: {
-          lexical: 0,
-          semantic: 0,
-          recency: 0,
-          entity: 0,
+          semantic: recall.semanticHits,
+          recency: recall.recencyHits,
         },
       };
       return {
@@ -354,28 +329,18 @@ export async function handleMemoryRecall(
       };
     }
 
-    // Format candidates into readable text using the shared formatter
-    const formatted = formatRecallText(candidates, {
-      format: config.memory.retrieval.injectionFormat,
-      maxTokens: config.memory.retrieval.maxInjectTokens,
-    });
-
-    const items = formatted.selected.map((c) => ({
-      id: c.id,
-      type: c.type,
-      kind: c.kind,
-    }));
-
     const result: MemoryRecallToolResult = {
-      text: formatted.text,
-      resultCount: formatted.selected.length,
+      text: recall.injectedText,
+      resultCount: recall.selectedCount,
       degraded,
-      items,
+      items: recall.topCandidates.map((c) => ({
+        id: c.key,
+        type: c.type,
+        kind: c.kind,
+      })),
       sources: {
-        lexical: collected.lexical.length,
-        semantic: collected.semantic.length,
-        recency: collected.recency.length,
-        entity: collected.entity.length,
+        semantic: recall.semanticHits,
+        recency: recall.recencyHits,
       },
     };
 

package/src/tools/schedule/create.ts

@@ -22,8 +22,15 @@ const VALID_ROUTING_INTENTS: RoutingIntent[] = [
 
 export async function executeScheduleCreate(
   input: Record<string, unknown>,
-  _context: ToolContext,
+  context: ToolContext,
 ): Promise<ToolExecutionResult> {
+  if (context.trustClass !== "guardian") {
+    return {
+      content:
+        "Error: schedule_create is restricted to guardian actors because schedules execute with elevated privileges.",
+      isError: true,
+    };
+  }
   const name = input.name as string;
   const timezone = (input.timezone as string) ?? null;
   const message = input.message as string;

package/src/tools/schedule/update.ts

@@ -25,8 +25,15 @@ const VALID_ROUTING_INTENTS: RoutingIntent[] = [
 
 export async function executeScheduleUpdate(
   input: Record<string, unknown>,
-  _context: ToolContext,
+  context: ToolContext,
 ): Promise<ToolExecutionResult> {
+  if (context.trustClass !== "guardian") {
+    return {
+      content:
+        "Error: schedule_update is restricted to guardian actors because schedules execute with elevated privileges.",
+      isError: true,
+    };
+  }
   const jobId = input.job_id as string;
   if (!jobId || typeof jobId !== "string") {
     return { content: "Error: job_id is required", isError: true };

package/src/tools/skills/load.ts

@@ -8,7 +8,10 @@ import type { SkillSummary, SkillToolManifest } from "../../config/skills.js";
 import { loadSkillBySelector, loadSkillCatalog } from "../../config/skills.js";
 import { RiskLevel } from "../../permissions/types.js";
 import type { ToolDefinition } from "../../providers/types.js";
-import { autoInstallFromCatalog } from "../../skills/catalog-install.js";
+import {
+  autoInstallFromCatalog,
+  resolveCatalog,
+} from "../../skills/catalog-install.js";
 import {
   collectAllMissing,
   indexCatalogById,
@@ -191,15 +194,35 @@ export class SkillLoadTool implements Tool {
       catalogIndex = indexCatalogById(catalog);
 
       // Auto-install missing includes before validation (max 5 rounds for transitive deps)
+      // Defer catalog resolution until we confirm there are missing includes,
+      // then cache the result to avoid redundant network requests per dependency.
+      let remoteCatalog: Awaited<ReturnType<typeof resolveCatalog>> | undefined;
+
       const MAX_INSTALL_ROUNDS = 5;
       for (let round = 0; round < MAX_INSTALL_ROUNDS; round++) {
         const missing = collectAllMissing(skill.id, catalogIndex);
         if (missing.size === 0) break;
 
+        // Lazily resolve catalog on first round with missing includes
+        if (!remoteCatalog) {
+          try {
+            remoteCatalog = await resolveCatalog([...missing][0]);
+          } catch (err) {
+            log.warn(
+              { err, skillId: skill.id },
+              "Failed to resolve catalog for include auto-install",
+            );
+            break;
+          }
+        }
+
         let installedAny = false;
         for (const missingId of missing) {
           try {
-            const installed = await autoInstallFromCatalog(missingId);
+            const installed = await autoInstallFromCatalog(
+              missingId,
+              remoteCatalog,
+            );
             if (installed) {
               log.info(
                 { skillId: missingId, parentSkillId: skill.id },