@vellumai/assistant 0.12.2-staging.4 → 0.12.2-staging.5

package/src/tools/skills/find-similar-skills.test.ts

@@ -14,10 +14,12 @@
  * `readInstallMeta` seam is mocked to key off the skill id (its dir basename).
  */
 
-import { basename } from "node:path";
-import { describe, expect, mock, test } from "bun:test";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { afterEach, describe, expect, mock, test } from "bun:test";
 
 import type { SkillSource } from "../../config/skills.js";
+import type { StoredManagedSkill } from "../../skills/managed-store.js";
 import type { OwnerInfo } from "../types.js";
 
 // Map managed skill id → recorded author, consulted by the mocked
@@ -44,6 +46,11 @@ function makeContext(enabledPluginSet?: Set<string> | null): ToolContext {
   };
 }
 
+/** A retrospective-pass tool context: the one caller handed `current`. */
+function makeRetrospectiveContext(): ToolContext {
+  return { ...makeContext(), requestOrigin: "memory_retrospective" };
+}
+
 const catalog = (
   ...skills: {
     id: string;
@@ -217,6 +224,208 @@ describe("find_similar_skills — enrichment", () => {
   });
 });
 
+describe("find_similar_skills: current skill for a refinable hit", () => {
+  afterEach(() => {
+    rmSync(join(process.env.VELLUM_WORKSPACE_DIR!, "skills"), {
+      recursive: true,
+      force: true,
+    });
+  });
+
+  const refinableCatalog = () =>
+    catalog(
+      {
+        id: "weekly-export",
+        name: "Weekly Report Export",
+        description: "Export the weekly usage report",
+        source: "managed",
+      },
+      {
+        id: "user-skill",
+        name: "User Skill",
+        description: "A person wrote this",
+        source: "managed",
+      },
+      {
+        id: "clean-disk",
+        name: "Clean Disk",
+        description: "Free up disk space",
+        source: "bundled",
+      },
+    );
+  const stored: Record<string, StoredManagedSkill> = {
+    "weekly-export": {
+      name: "Weekly Report Export",
+      description: "Export the weekly usage report",
+      emoji: "📊",
+      category: "productivity",
+      includes: ["csv-basics"],
+      activationHints: ["user asks for the weekly report"],
+      avoidWhen: ["the report is monthly"],
+      body: "1. Open the dashboard.\n2. Export.",
+    },
+    "user-skill": {
+      name: "User Skill",
+      description: "A person wrote this",
+      body: "Do the user's thing.",
+    },
+    "clean-disk": {
+      name: "Clean Disk",
+      description: "Free up disk space",
+      body: "Delete caches.",
+    },
+  };
+  const reads: string[] = [];
+  const readStoredManagedSkill = (skillId: string) => {
+    reads.push(skillId);
+    return stored[skillId] ?? null;
+  };
+  const hits = async () => [
+    { skillId: "weekly-export", score: 0.9 },
+    { skillId: "user-skill", score: 0.8 },
+    { skillId: "clean-disk", score: 0.7 },
+  ];
+
+  test("the retrospective gets the skill as it is, in scaffold argument names, only for its own managed hits", async () => {
+    installMetaAuthors["weekly-export"] = "assistant";
+    installMetaAuthors["user-skill"] = "user";
+
+    const result = await executeFindSimilarSkills(
+      { goal: "export the weekly report" },
+      makeRetrospectiveContext(),
+      {
+        nearestExistingSkills: hits,
+        loadCatalog: refinableCatalog,
+        readStoredManagedSkill,
+      },
+    );
+
+    const { skills } = JSON.parse(result.content);
+    expect(skills[0].current).toEqual({
+      name: "Weekly Report Export",
+      description: "Export the weekly usage report",
+      emoji: "📊",
+      category: "productivity",
+      includes: ["csv-basics"],
+      activation_hints: ["user asks for the weekly report"],
+      avoid_when: ["the report is monthly"],
+      body_markdown: "1. Open the dashboard.\n2. Export.",
+    });
+    // A person's skill and a bundled skill are not the pass's to refine, so
+    // their content is not handed over.
+    expect(skills[1]).not.toHaveProperty("current");
+    expect(skills[2]).not.toHaveProperty("current");
+  });
+
+  test("absent frontmatter fields are omitted rather than sent as null", async () => {
+    installMetaAuthors["user-skill"] = "assistant";
+
+    const result = await executeFindSimilarSkills(
+      { goal: "the user's thing" },
+      makeRetrospectiveContext(),
+      {
+        nearestExistingSkills: async () => [
+          { skillId: "user-skill", score: 1 },
+        ],
+        loadCatalog: refinableCatalog,
+        readStoredManagedSkill,
+      },
+    );
+
+    const { skills } = JSON.parse(result.content);
+    expect(skills[0].current).toEqual({
+      name: "User Skill",
+      description: "A person wrote this",
+      body_markdown: "Do the user's thing.",
+    });
+  });
+
+  test("an interactive caller never receives skill bodies, and no body is read", async () => {
+    installMetaAuthors["weekly-export"] = "assistant";
+    reads.length = 0;
+
+    const result = await executeFindSimilarSkills(
+      { goal: "export the weekly report" },
+      makeContext(),
+      {
+        nearestExistingSkills: hits,
+        loadCatalog: refinableCatalog,
+        readStoredManagedSkill,
+      },
+    );
+
+    const { skills } = JSON.parse(result.content);
+    for (const skill of skills) {
+      expect(skill).not.toHaveProperty("current");
+    }
+    expect(reads).toEqual([]);
+  });
+
+  test("the stored body keeps its leading indentation and drops only the store's separator newlines", async () => {
+    // The real reader, against a real SKILL.md: a body opening with an
+    // indented code block must come back indented, or a refinement that
+    // copies it turns the block into prose.
+    const skillsDir = join(process.env.VELLUM_WORKSPACE_DIR!, "skills");
+    mkdirSync(join(skillsDir, "indented"), { recursive: true });
+    writeFileSync(
+      join(skillsDir, "indented", "SKILL.md"),
+      [
+        "---",
+        'name: "Indented"',
+        'description: "Opens with a code block"',
+        "---",
+        "",
+        "    curl https://example.com/report",
+        "",
+        "Then read the output.",
+        "",
+      ].join("\n"),
+    );
+    installMetaAuthors["indented"] = "assistant";
+
+    const result = await executeFindSimilarSkills(
+      { goal: "fetch the report" },
+      makeRetrospectiveContext(),
+      {
+        nearestExistingSkills: async () => [{ skillId: "indented", score: 1 }],
+        loadCatalog: () =>
+          catalog({
+            id: "indented",
+            name: "Indented",
+            description: "Opens with a code block",
+            source: "managed",
+          }),
+      },
+    );
+
+    const { skills } = JSON.parse(result.content);
+    expect(skills[0].current.body_markdown).toBe(
+      "    curl https://example.com/report\n\nThen read the output.",
+    );
+  });
+
+  test("a skill that cannot be read drops current, not the hit", async () => {
+    installMetaAuthors["weekly-export"] = "assistant";
+
+    const result = await executeFindSimilarSkills(
+      { goal: "export the weekly report" },
+      makeRetrospectiveContext(),
+      {
+        nearestExistingSkills: async () => [
+          { skillId: "weekly-export", score: 0.9 },
+        ],
+        loadCatalog: refinableCatalog,
+        readStoredManagedSkill: () => null,
+      },
+    );
+
+    const { skills } = JSON.parse(result.content);
+    expect(skills).toHaveLength(1);
+    expect(skills[0].skill_id).toBe("weekly-export");
+    expect(skills[0]).not.toHaveProperty("current");
+  });
+});
+
 describe("find_similar_skills — per-chat plugin scope", () => {
   const SHORTLIST = [
     { skillId: "core-skill", score: 0.9 },

package/src/tools/skills/find-similar-skills.ts

@@ -1,8 +1,13 @@
 import type { SkillSource } from "../../config/skills.js";
 import { loadSkillCatalog } from "../../config/skills.js";
+import { MEMORY_RETROSPECTIVE_ORIGIN } from "../../plugins/defaults/memory/memory-retrospective-constants.js";
 import { nearestExistingSkills } from "../../plugins/defaults/memory/v3/candidate-match.js";
 import { readInstallMeta } from "../../skills/install-meta.js";
-import { getManagedSkillDir } from "../../skills/managed-store.js";
+import {
+  getManagedSkillDir,
+  readStoredManagedSkill,
+  type StoredManagedSkill,
+} from "../../skills/managed-store.js";
 import {
   filterSkillsByPlatform,
   type SkillPlatform,
@@ -21,6 +26,14 @@ import type { OwnerInfo, ToolContext, ToolExecutionResult } from "../types.js";
  * `"user"` = a person wrote it, off-limits). It is undefined for non-managed
  * sources and for managed skills with no recorded author, so the caller can
  * distinguish its OWN managed skills from a user's without re-reading meta.
+ *
+ * `current` is the skill as stored, present only on a hit the caller may
+ * refine (managed, assistant-authored) and only for the retrospective. A
+ * refinement is a whole-file overwrite and the pass has no other read path:
+ * its `skill_load` grant covers skill-management alone, and loading would
+ * stamp `lastUsedAt` and count as usage. Fields are spelled as
+ * `scaffold_managed_skill`'s own arguments so the pass carries forward what
+ * it is not changing without translating names.
  */
 interface EnrichedHit {
   skill_id: string;
@@ -29,6 +42,19 @@ interface EnrichedHit {
   source: SkillSource;
   author?: "assistant" | "user";
   score: number;
+  current?: CurrentSkill;
+}
+
+/** The refinable skill's present content, in `scaffold_managed_skill` argument names. */
+interface CurrentSkill {
+  name: string;
+  description: string;
+  emoji?: string;
+  category?: string;
+  includes?: string[];
+  activation_hints?: string[];
+  avoid_when?: string[];
+  body_markdown: string;
 }
 
 /**
@@ -37,7 +63,8 @@ interface EnrichedHit {
  * each joined to its catalog name/description. Exported so bundled-skill
  * executors and tests can call it directly.
  *
- * `deps` injects the shortlist + catalog seams so tests run without Qdrant.
+ * `deps` injects the shortlist, catalog, and stored-skill seams so tests run
+ * without Qdrant or a skills directory.
  */
 export async function executeFindSimilarSkills(
   input: Record<string, unknown>,
@@ -52,6 +79,7 @@ export async function executeFindSimilarSkills(
       owner?: OwnerInfo;
       platforms?: SkillPlatform[];
     }[];
+    readStoredManagedSkill?: (skillId: string) => StoredManagedSkill | null;
   } = {},
 ): Promise<ToolExecutionResult> {
   const goal = input.goal;
@@ -79,6 +107,7 @@ export async function executeFindSimilarSkills(
 
   const findNearest = deps.nearestExistingSkills ?? nearestExistingSkills;
   const loadCatalog = deps.loadCatalog ?? (() => loadSkillCatalog());
+  const readStored = deps.readStoredManagedSkill ?? readStoredManagedSkill;
 
   const catalog = loadCatalog();
   const byId = new Map(catalog.map((s) => [s.id, s]));
@@ -114,6 +143,9 @@ export async function executeFindSimilarSkills(
     ...(context.signal ? { signal: context.signal } : {}),
   });
 
+  const fromRetrospective =
+    context.requestOrigin === MEMORY_RETROSPECTIVE_ORIGIN;
+
   const enriched: EnrichedHit[] = [];
   for (const hit of hits) {
     const skill = byId.get(hit.skillId);
@@ -126,19 +158,40 @@ export async function executeFindSimilarSkills(
     if (outOfScope(skill)) {
       continue;
     }
+    // Join install-meta authorship for managed hits so the caller can tell its
+    // OWN skills (overwritable) from a user's. Best-effort: an absent/failed
+    // meta read leaves `author` undefined rather than throwing.
+    const author =
+      skill.source === "managed"
+        ? readManagedSkillAuthor(hit.skillId)
+        : undefined;
+    // Only a refinable hit pays for the disk read, and a failed read drops
+    // `current` rather than the hit: the pass can still skip a skill it
+    // cannot see, it just cannot rewrite it well. Absent fields serialize
+    // away with the result.
+    const stored =
+      fromRetrospective && author === "assistant"
+        ? readStored(hit.skillId)
+        : null;
     enriched.push({
       skill_id: hit.skillId,
       name: skill.name,
       description: skill.description,
       source: skill.source,
-      // Join install-meta authorship for managed hits so the caller can tell its
-      // OWN skills (overwritable) from a user's. Best-effort: an absent/failed
-      // meta read leaves `author` undefined rather than throwing.
-      author:
-        skill.source === "managed"
-          ? readManagedSkillAuthor(hit.skillId)
-          : undefined,
+      author,
       score: hit.score,
+      current: stored
+        ? {
+            name: stored.name,
+            description: stored.description,
+            emoji: stored.emoji,
+            category: stored.category,
+            includes: stored.includes,
+            activation_hints: stored.activationHints,
+            avoid_when: stored.avoidWhen,
+            body_markdown: stored.body,
+          }
+        : undefined,
     });
   }