@vellumai/assistant 0.8.1 → 0.8.3

package/src/memory/v2/skill-store.ts

@@ -36,6 +36,7 @@ import {
 } from "../embedding-backend.js";
 import { invalidatePageIndex } from "./page-index.js";
 import {
+  backfillKindOnPointsWithPrefix,
   pruneSlugsWithPrefixExcept,
   upsertConceptPageEmbedding,
 } from "./qdrant.js";
@@ -78,6 +79,11 @@ export function skillSlugFor(id: string): string {
  * successful re-seed so callers always see a consistent snapshot.
  */
 let entries: Map<string, SkillEntry> | null = null;
+let requestedSeedGeneration = 0;
+let processedSeedGeneration = 0;
+let activeSeedDrain: Promise<void> | null = null;
+let lastSeedError: unknown = null;
+const seedWaiters: Array<{ generation: number; resolve: () => void }> = [];
 
 /**
  * Seed (or re-seed) skill embeddings into the unified concept-page collection.
@@ -85,32 +91,19 @@ let entries: Map<string, SkillEntry> | null = null;
  * background callers like daemon startup; pass `{ throwOnError: true }` from
  * synchronous CLI-driven paths that need to surface failures to the operator.
  *
- * Single-flight + coalesced: at most one seed runs at a time, and concurrent
- * callers are coalesced into one follow-up re-snapshot that runs after the
- * in-flight seed completes. Without this, an older snapshot can finish after
- * a newer one and overwrite the newer skill state. Strict callers observe
- * the most recent run's outcome via `lastSeedError`.
+ * Single-flight + coalesced: at most one seed runs at a time. Requests made
+ * while a seed is in flight advance the requested generation; stale in-flight
+ * snapshots are skipped before they write embeddings or replace the cache,
+ * then the drain loop immediately processes the latest generation. Strict
+ * callers observe the awaited generation's latest outcome via `lastSeedError`.
  */
-let seedTail: Promise<void> = Promise.resolve();
-let seedPending: Promise<void> | null = null;
-let lastSeedError: unknown = null;
 
-export async function seedV2SkillEntries(
-  opts: { throwOnError?: boolean } = {},
-): Promise<void> {
-  if (!seedPending) {
-    const next = seedTail.then(async () => {
-      seedPending = null;
-      await runSeedOnce();
-    });
-    seedTail = next.catch(() => {});
-    seedPending = next;
-  }
-  await seedPending;
-  if (opts.throwOnError && lastSeedError) {
-    throw lastSeedError;
-  }
-}
+/**
+ * In-process latch for the legacy `kind` backfill (see
+ * {@link backfillKindOnPointsWithPrefix}). New upserts always write `kind`,
+ * so once the latch is set there is no follow-up work to do this process.
+ */
+let legacyKindBackfillDone = false;
 
 /**
  * Steps (per run):
@@ -132,7 +125,49 @@ export async function seedV2SkillEntries(
  *      stale points from prior catalog state (e.g. uninstalled skills).
  *   7. Replace the module-level `entries` cache with the freshly built map.
  */
-async function runSeedOnce(): Promise<void> {
+export async function seedV2SkillEntries(
+  opts: { throwOnError?: boolean } = {},
+): Promise<void> {
+  const generation = ++requestedSeedGeneration;
+  const waiter = new Promise<void>((resolve) => {
+    seedWaiters.push({ generation, resolve });
+  });
+  startSeedDrainIfNeeded();
+  await waiter;
+  if (opts.throwOnError && lastSeedError) {
+    throw lastSeedError;
+  }
+}
+
+function startSeedDrainIfNeeded(): void {
+  if (activeSeedDrain) return;
+  if (processedSeedGeneration >= requestedSeedGeneration) return;
+
+  activeSeedDrain = drainSeedQueue().finally(() => {
+    activeSeedDrain = null;
+    startSeedDrainIfNeeded();
+  });
+}
+
+async function drainSeedQueue(): Promise<void> {
+  while (processedSeedGeneration < requestedSeedGeneration) {
+    const generationToProcess = requestedSeedGeneration;
+    await runSeedV2SkillEntries(generationToProcess);
+    processedSeedGeneration = generationToProcess;
+    resolveSeedWaiters();
+  }
+}
+
+function resolveSeedWaiters(): void {
+  for (let i = seedWaiters.length - 1; i >= 0; i -= 1) {
+    const waiter = seedWaiters[i]!;
+    if (waiter.generation > processedSeedGeneration) continue;
+    seedWaiters.splice(i, 1);
+    waiter.resolve();
+  }
+}
+
+async function runSeedV2SkillEntries(generation: number): Promise<void> {
   try {
     const config = getConfig();
     const catalog = loadSkillCatalog();
@@ -160,11 +195,19 @@ async function runSeedOnce(): Promise<void> {
     // Seed uninstalled catalog skills so their activation hints are
     // discoverable by intent. Track whether the catalog was available so we
     // can guard pruning below.
+    //
+    // Build the legacy-backfill allowlist in parallel: every locally
+    // installed skill id (regardless of enabled state) plus every remote
+    // catalog id. Restricting the backfill to this set keeps user-authored
+    // concept pages that happen to live under `skills/<slug>` from being
+    // mis-tagged and then pruned. See `backfillKindOnPointsWithPrefix`.
+    const knownSkillIds = new Set<string>(installedIds);
     let catalogAvailable = false;
     try {
       const fullCatalog = await getCatalog();
       catalogAvailable = fullCatalog.length > 0;
       for (const entry of fullCatalog) {
+        knownSkillIds.add(entry.id);
         if (installedIds.has(entry.id)) continue;
         const flagKey = entry.metadata?.vellum?.["feature-flag"];
         if (flagKey && !isAssistantFeatureFlagEnabled(flagKey, config))
@@ -184,12 +227,16 @@ async function runSeedOnce(): Promise<void> {
     // unavailable embedding backend in the all-disabled case, so pruning and
     // cache replacement still run and clear stale state.
     const nextEntries = new Map<string, SkillEntry>();
+    let denseVectors: number[][] = [];
+    let encodeSparse: (
+      input: string,
+    ) => ReturnType<typeof generateSparseEmbedding> = generateSparseEmbedding;
     if (seeds.length > 0) {
       const embedded = await embedWithBackend(
         config,
         seeds.map((s) => s.content),
       );
-      const denseVectors = await Promise.all(
+      denseVectors = await Promise.all(
         embedded.vectors.map((v) =>
           applyCorrectionIfCalibrated(v, embedded.provider, embedded.model),
         ),
@@ -203,14 +250,25 @@ async function runSeedOnce(): Promise<void> {
       // entirely. Fall back to the legacy TF encoder only during the cold-start
       // window before corpus stats finish building.
       const corpusStats = getConceptPageCorpusStats();
-      const encodeSparse = (input: string) =>
+      encodeSparse = (input: string) =>
         corpusStats
           ? generateBm25DocEmbedding(input, corpusStats, {
               k1: config.memory.v2.bm25_k1,
               b: config.memory.v2.bm25_b,
             })
           : generateSparseEmbedding(input);
+    }
 
+    if (generation !== requestedSeedGeneration) {
+      log.info(
+        { generation, latestGeneration: requestedSeedGeneration },
+        "Skipping stale v2 skill seed result",
+      );
+      lastSeedError = null;
+      return;
+    }
+
+    if (seeds.length > 0) {
       const now = Date.now();
       await Promise.all(
         seeds.map((seed, i) =>
@@ -233,6 +291,25 @@ async function runSeedOnce(): Promise<void> {
     // uninstalled catalog skills should exist, so skip pruning entirely to
     // avoid aggressively removing previously-seeded catalog skill embeddings.
     if (catalogAvailable) {
+      // Tag legacy skill points missing `payload.kind` before pruning so the
+      // kind-scoped prune can see them. Once-per-process; the backfill is
+      // idempotent (server-side `is_empty` filter), so a partial failure
+      // converges on retry.
+      if (!legacyKindBackfillDone) {
+        try {
+          await backfillKindOnPointsWithPrefix(
+            SKILL_SLUG_PREFIX,
+            SKILL_PAYLOAD_KIND,
+            knownSkillIds,
+          );
+          legacyKindBackfillDone = true;
+        } catch (err) {
+          log.warn(
+            { err },
+            "Failed to backfill kind on legacy skill points — pruning may leave orphans this run",
+          );
+        }
+      }
       await pruneSlugsWithPrefixExcept(
         SKILL_SLUG_PREFIX,
         seeds.map((s) => s.id),
@@ -265,12 +342,16 @@ async function runSeedOnce(): Promise<void> {
  * Accepts either a bare skill id (`example-skill`) or its unified-collection
  * slug (`skills/example-skill`) so render-side callers can pass through what
  * they have without a manual prefix strip.
+ *
+ * Returns a frozen copy so callers cannot mutate the underlying cache entry
+ * — matches the defensive-copy contract of `listSkillEntries`.
  */
 export function getSkillCapability(idOrSlug: string): SkillEntry | null {
   const id = idOrSlug.startsWith(SKILL_SLUG_PREFIX)
     ? idOrSlug.slice(SKILL_SLUG_PREFIX.length)
     : idOrSlug;
-  return entries?.get(id) ?? null;
+  const entry = entries?.get(id);
+  return entry ? Object.freeze({ ...entry }) : null;
 }
 
 /** True iff the slug refers to a skill entry in the unified collection. */
@@ -280,8 +361,9 @@ export function isSkillSlug(slug: string): boolean {
 
 /**
  * Snapshot of the in-process skill cache, sorted by skill id (ASCII order)
- * for determinism. Returns a freshly allocated array on each call so callers
- * cannot mutate the underlying cache.
+ * for determinism. Returns a freshly allocated array of frozen entry copies
+ * on each call, so callers cannot mutate the underlying cache — neither by
+ * reassigning the array nor by writing through entry fields.
  *
  * The cache is replaced atomically by `seedV2SkillEntries`, so a snapshot
  * may be stale once a subsequent seed run completes. Callers that need
@@ -289,15 +371,18 @@ export function isSkillSlug(slug: string): boolean {
  */
 export function listSkillEntries(): SkillEntry[] {
   if (!entries) return [];
-  return [...entries.values()].sort((a, b) =>
-    a.id < b.id ? -1 : a.id > b.id ? 1 : 0,
-  );
+  return [...entries.values()]
+    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+    .map((entry) => Object.freeze({ ...entry }));
 }
 
 /** @internal Test-only: clear the module-level cache. */
 export function _resetSkillStoreForTests(): void {
   entries = null;
-  seedTail = Promise.resolve();
-  seedPending = null;
+  requestedSeedGeneration = 0;
+  processedSeedGeneration = 0;
+  activeSeedDrain = null;
+  seedWaiters.splice(0, seedWaiters.length);
   lastSeedError = null;
+  legacyKindBackfillDone = false;
 }

package/src/memory/v2/static-context.ts

@@ -35,9 +35,9 @@ const MEMORY_V2_STATIC_BLOCKS: readonly MemoryV2StaticBlock[] = [
 ];
 
 /**
- * Build the v2 static memory block, gated on `config.memory.v2.enabled`.
- * Empty/missing files are skipped; returns `null` when the gate is off or
- * every file is empty.
+ * Build the v2 static memory block, gated on `config.memory.enabled` and
+ * `config.memory.v2.enabled`. Empty/missing files are skipped; returns `null`
+ * when either gate is off or every file is empty.
  */
 export function readMemoryV2StaticContent(): string | null {
   let config;
@@ -46,7 +46,7 @@ export function readMemoryV2StaticContent(): string | null {
   } catch {
     return null;
   }
-  if (!config.memory.v2.enabled) {
+  if (!config.memory.enabled || !config.memory.v2.enabled) {
     return null;
   }
 

package/src/memory/v2/types.ts

@@ -115,3 +115,26 @@ export interface SkillEntry {
   id: string;
   content: string;
 }
+
+// ---------------------------------------------------------------------------
+// CLI-command entries (synthetic concept-collection rows, not on-disk pages)
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-CLI-subcommand capability snapshot held in-process and embedded into the
+ * unified `memory_v2_concept_pages` Qdrant collection under the slug
+ * `cli-commands/<name>`. `content` is the full `helpInformation()` output for
+ * the top-level subcommand — the embedding target, intentionally uncapped so
+ * activation hints in flag descriptions and examples carry semantic weight.
+ * `description` is the one-line Commander description, rendered terse in
+ * `### CLI Commands You Can Use` so the injection block stays compact even
+ * for verbose `--help` outputs.
+ *
+ * Plain interface (no Zod) — same in-process-only justification as
+ * `SkillEntry`.
+ */
+export interface CliCommandEntry {
+  id: string;
+  description: string;
+  content: string;
+}

package/src/messaging/providers/a2a/__tests__/deliver.test.ts

@@ -0,0 +1,274 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { ChannelReplyPayload } from "@vellumai/gateway-client";
+
+import type { A2ATask, Artifact } from "../../../../a2a/protocol-types.js";
+
+// ---------------------------------------------------------------------------
+// Mock state
+// ---------------------------------------------------------------------------
+
+let completedTask: A2ATask | null = null;
+let completeWithArtifactsCalls: Array<{
+  taskId: string;
+  artifacts: Artifact[];
+}> = [];
+let pushUrlByTaskId: Record<string, string | null> = {};
+let completeError: Error | null = null;
+
+const fetchCalls: Array<{
+  url: string;
+  init: RequestInit;
+}> = [];
+let fetchResponses: Array<{ ok: boolean; status: number; body: string }> = [];
+let fetchCallIndex = 0;
+
+// ---------------------------------------------------------------------------
+// Mocks
+// ---------------------------------------------------------------------------
+
+const defaultTask: A2ATask = {
+  id: "task-123",
+  status: { state: "completed", timestamp: new Date().toISOString() },
+  artifacts: [
+    {
+      artifact_id: "art-1",
+      parts: [{ kind: "text", text: "Hello from assistant" }],
+    },
+  ],
+};
+
+mock.module("../../../../a2a/task-store.js", () => ({
+  completeWithArtifacts: (taskId: string, artifacts: Artifact[]): A2ATask => {
+    completeWithArtifactsCalls.push({ taskId, artifacts });
+    if (completeError) throw completeError;
+    return completedTask ?? defaultTask;
+  },
+  getPushUrl: (taskId: string): string | null => {
+    return pushUrlByTaskId[taskId] ?? null;
+  },
+}));
+
+mock.module("../../../../util/logger.js", () => ({
+  getLogger: () => ({
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+  }),
+}));
+
+// Intercept global fetch for push notification testing
+const originalFetch = globalThis.fetch;
+
+// Import the module under test AFTER mocks are set up
+const { deliverA2AReply } = await import("../deliver.js");
+
+// ---------------------------------------------------------------------------
+// Setup / teardown
+// ---------------------------------------------------------------------------
+
+beforeEach(() => {
+  completedTask = null;
+  completeWithArtifactsCalls = [];
+  pushUrlByTaskId = {};
+  completeError = null;
+  fetchCalls.length = 0;
+  fetchResponses = [];
+  fetchCallIndex = 0;
+
+  globalThis.fetch = (async (
+    input: string | URL | Request,
+    init?: RequestInit,
+  ) => {
+    const url = typeof input === "string" ? input : input.toString();
+    fetchCalls.push({ url, init: init ?? {} });
+    const responseSpec = fetchResponses[fetchCallIndex++] ?? {
+      ok: true,
+      status: 200,
+      body: "{}",
+    };
+    return new Response(responseSpec.body, {
+      status: responseSpec.status,
+      statusText: responseSpec.ok ? "OK" : "Error",
+    });
+  }) as typeof fetch;
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("deliverA2AReply", () => {
+  const baseCallbackUrl = "https://example.com/deliver/a2a?taskId=task-123";
+
+  test("completes task with text artifact", async () => {
+    const payload: ChannelReplyPayload = {
+      chatId: "chat-1",
+      text: "Hello from the assistant",
+    };
+
+    const result = await deliverA2AReply(baseCallbackUrl, payload);
+
+    expect(result.ok).toBe(true);
+    expect(completeWithArtifactsCalls).toHaveLength(1);
+    expect(completeWithArtifactsCalls[0].taskId).toBe("task-123");
+    expect(completeWithArtifactsCalls[0].artifacts).toHaveLength(1);
+    expect(completeWithArtifactsCalls[0].artifacts[0].parts).toEqual([
+      { kind: "text", text: "Hello from the assistant" },
+    ]);
+  });
+
+  test("completes task with file attachments", async () => {
+    const payload: ChannelReplyPayload = {
+      chatId: "chat-1",
+      text: "Here is a file",
+      attachments: [
+        {
+          id: "att-1",
+          filename: "report.pdf",
+          mimeType: "application/pdf",
+          sizeBytes: 1024,
+          kind: "file",
+          data: "data:application/pdf;base64,abc123",
+        },
+      ],
+    };
+
+    const result = await deliverA2AReply(baseCallbackUrl, payload);
+
+    expect(result.ok).toBe(true);
+    expect(completeWithArtifactsCalls).toHaveLength(1);
+    const parts = completeWithArtifactsCalls[0].artifacts[0].parts;
+    expect(parts).toHaveLength(2);
+    expect(parts[0]).toEqual({
+      kind: "text",
+      text: "Here is a file",
+    });
+    expect(parts[1]).toEqual({
+      kind: "file",
+      filename: "report.pdf",
+      media_type: "application/pdf",
+      url: "data:application/pdf;base64,abc123",
+    });
+  });
+
+  test("returns ok: false when taskId is missing from URL", async () => {
+    const result = await deliverA2AReply("https://example.com/deliver/a2a", {
+      chatId: "chat-1",
+      text: "Hello",
+    });
+
+    expect(result.ok).toBe(false);
+    expect(completeWithArtifactsCalls).toHaveLength(0);
+  });
+
+  test("returns ok: true when payload has no content", async () => {
+    const result = await deliverA2AReply(baseCallbackUrl, {
+      chatId: "chat-1",
+    });
+
+    expect(result.ok).toBe(true);
+    expect(completeWithArtifactsCalls).toHaveLength(0);
+  });
+
+  test("returns ok: false when task completion throws", async () => {
+    completeError = new Error("A2A task not found: task-123");
+
+    const result = await deliverA2AReply(baseCallbackUrl, {
+      chatId: "chat-1",
+      text: "Hello",
+    });
+
+    expect(result.ok).toBe(false);
+  });
+
+  test("returns ok: false when task is already terminal", async () => {
+    completeError = new Error(
+      'Cannot transition task task-123 from terminal state "completed" to "completed"',
+    );
+
+    const result = await deliverA2AReply(baseCallbackUrl, {
+      chatId: "chat-1",
+      text: "Hello",
+    });
+
+    expect(result.ok).toBe(false);
+  });
+
+  describe("push notifications", () => {
+    test("POSTs completed task to push URL", async () => {
+      pushUrlByTaskId["task-123"] = "https://requester.example.com/push";
+      fetchResponses = [{ ok: true, status: 200, body: "{}" }];
+
+      const result = await deliverA2AReply(baseCallbackUrl, {
+        chatId: "chat-1",
+        text: "Done",
+      });
+
+      expect(result.ok).toBe(true);
+
+      // Wait for the fire-and-forget push to complete
+      await new Promise((r) => setTimeout(r, 50));
+
+      expect(fetchCalls).toHaveLength(1);
+      expect(fetchCalls[0].url).toBe("https://requester.example.com/push");
+      expect(fetchCalls[0].init.method).toBe("POST");
+
+      const headers = fetchCalls[0].init.headers as Record<string, string>;
+      expect(headers["Content-Type"]).toBe("application/a2a+json");
+      expect(headers["A2A-Version"]).toBe("1.0");
+    });
+
+    test("does not push when no push URL configured", async () => {
+      const result = await deliverA2AReply(baseCallbackUrl, {
+        chatId: "chat-1",
+        text: "Done",
+      });
+
+      expect(result.ok).toBe(true);
+
+      await new Promise((r) => setTimeout(r, 50));
+
+      expect(fetchCalls).toHaveLength(0);
+    });
+
+    test("push failure does not affect delivery result", async () => {
+      pushUrlByTaskId["task-123"] = "https://requester.example.com/push";
+      // All retries fail with 500
+      fetchResponses = Array(4).fill({
+        ok: false,
+        status: 500,
+        body: "Internal Server Error",
+      });
+
+      const result = await deliverA2AReply(baseCallbackUrl, {
+        chatId: "chat-1",
+        text: "Done",
+      });
+
+      // Delivery still succeeds even though push will fail
+      expect(result.ok).toBe(true);
+    });
+
+    test("stops retrying on non-retryable client error", async () => {
+      pushUrlByTaskId["task-123"] = "https://requester.example.com/push";
+      fetchResponses = [{ ok: false, status: 404, body: "Not Found" }];
+
+      await deliverA2AReply(baseCallbackUrl, {
+        chatId: "chat-1",
+        text: "Done",
+      });
+
+      // Wait for the fire-and-forget push to settle
+      await new Promise((r) => setTimeout(r, 50));
+
+      // Should only attempt once on a 4xx (non-429) error
+      expect(fetchCalls).toHaveLength(1);
+    });
+  });
+});