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

package/src/skills/managed-store.ts

@@ -14,10 +14,13 @@ import { dirname, isAbsolute, join, normalize, relative, sep } from "node:path";
 
 import { stringify as stringifyYaml } from "yaml";
 
+import { parseFrontmatter } from "../config/skills.js";
 import { deleteSkillCapabilityNode } from "../plugins/defaults/memory/graph/capability-seed.js";
 import { isDeniedBasename } from "../tools/shared/filesystem/path-policy.js";
 import { getLogger } from "../util/logger.js";
+import { isPlainObject } from "../util/object.js";
 import { getWorkspaceDir, getWorkspaceSkillsDir } from "../util/platform.js";
+import { parseFrontmatterFields } from "./frontmatter.js";
 import { writeInstallMeta } from "./install-meta.js";
 
 const log = getLogger("managed-store");
@@ -210,11 +213,48 @@ interface BuildSkillMarkdownInput {
   name: string;
   description: string;
   bodyMarkdown: string;
+  /**
+   * The five fields the scaffold tool owns. `undefined` leaves whatever
+   * `preserve` carries for that field (nothing, on a create); an empty value
+   * clears it; a value sets it.
+   */
   emoji?: string;
   includes?: string[];
   activationHints?: string[];
   avoidWhen?: string[];
   category?: string;
+  /**
+   * The skill's existing frontmatter, as parsed from disk, for an overwrite.
+   * Every key survives except `name`, `description`, and the five fields
+   * above, so a `platforms` gate, a `display-name`, or custom metadata a
+   * person added by hand is not lost to a call that never mentions it.
+   */
+  preserve?: Record<string, unknown>;
+}
+
+/**
+ * Apply one tool-owned field to the vellum block: an input left `undefined`
+ * keeps the preserved value, an input given but empty (`value` undefined)
+ * clears it, and a value sets it.
+ */
+function setOrClear(
+  target: Record<string, unknown>,
+  key: string,
+  value: unknown,
+  input: unknown,
+): void {
+  if (input === undefined) {
+    return;
+  }
+  if (value === undefined) {
+    delete target[key];
+  } else {
+    target[key] = value;
+  }
+}
+
+function nonEmptyList(list: string[] | undefined): string[] | undefined {
+  return list && list.length > 0 ? list : undefined;
 }
 
 export function buildSkillMarkdown(input: BuildSkillMarkdownInput): string {
@@ -228,40 +268,55 @@ export function buildSkillMarkdown(input: BuildSkillMarkdownInput): string {
   lines.push(`name: "${esc(input.name)}"`);
   lines.push(`description: "${esc(input.description)}"`);
 
-  // Build metadata object matching the format parseFrontmatter expects:
-  // metadata:
-  //   vellum:
-  //     emoji: "..."
-  const vellum: Record<string, unknown> = {};
-  if (input.emoji) {
-    vellum.emoji = input.emoji;
-  }
-  if (input.includes && input.includes.length > 0) {
-    vellum.includes = input.includes;
-  }
-  // Kebab-case keys match what parseFrontmatter reads back
-  // (config/skills.ts: vellum["activation-hints"] / vellum["avoid-when"]).
-  // These flow through stringifyYaml below, which escapes/quotes values, so no
+  // Everything but name and description is emitted from one object: the
+  // preserved frontmatter with the tool-owned fields applied over it, under
+  // `metadata.vellum` where parseFrontmatter reads them back (kebab-case for
+  // the two list fields). stringifyYaml quotes and escapes values, so no
   // manual sanitization is needed here.
-  if (input.activationHints && input.activationHints.length > 0) {
-    vellum["activation-hints"] = input.activationHints;
+  const rest: Record<string, unknown> = structuredClone(input.preserve ?? {});
+  delete rest.name;
+  delete rest.description;
+  const metadata = isPlainObject(rest.metadata) ? rest.metadata : {};
+  const vellum = isPlainObject(metadata.vellum) ? metadata.vellum : {};
+  setOrClear(vellum, "emoji", input.emoji?.trim() || undefined, input.emoji);
+  // An emoji at the legacy `metadata.emoji` location wins over an absent
+  // vellum one on read, so a call that states the emoji retires it.
+  if (input.emoji !== undefined) {
+    delete metadata.emoji;
   }
-  if (input.avoidWhen && input.avoidWhen.length > 0) {
-    vellum["avoid-when"] = input.avoidWhen;
+  setOrClear(vellum, "includes", nonEmptyList(input.includes), input.includes);
+  setOrClear(
+    vellum,
+    "activation-hints",
+    nonEmptyList(input.activationHints),
+    input.activationHints,
+  );
+  setOrClear(
+    vellum,
+    "avoid-when",
+    nonEmptyList(input.avoidWhen),
+    input.avoidWhen,
+  );
+  // The web Skills UI buckets skills by this value; a blank one is a clear,
+  // never an empty bucket in the file.
+  setOrClear(
+    vellum,
+    "category",
+    input.category?.trim() || undefined,
+    input.category,
+  );
+  if (Object.keys(vellum).length > 0) {
+    metadata.vellum = vellum;
+  } else {
+    delete metadata.vellum;
   }
-  // The web Skills UI groups skills into a category sidebar by this value;
-  // skip it when blank so an empty bucket assignment never lands in frontmatter.
-  if (input.category?.trim()) {
-    vellum.category = input.category.trim();
+  if (Object.keys(metadata).length > 0) {
+    rest.metadata = metadata;
+  } else {
+    delete rest.metadata;
   }
-
-  if (Object.keys(vellum).length > 0) {
-    const metadata = { vellum };
-    const yamlBlock = stringifyYaml(metadata, { indent: 2 });
-    lines.push("metadata:");
-    for (const yamlLine of yamlBlock.trimEnd().split("\n")) {
-      lines.push(`  ${yamlLine}`);
-    }
+  if (Object.keys(rest).length > 0) {
+    lines.push(stringifyYaml(rest, { indent: 2 }).trimEnd());
   }
 
   lines.push("---");
@@ -348,7 +403,8 @@ export function createManagedSkill(
   const skillDir = getManagedSkillDir(params.id);
   const skillFilePath = join(skillDir, "SKILL.md");
 
-  if (existsSync(skillFilePath) && !params.overwrite) {
+  const skillExists = existsSync(skillFilePath);
+  if (skillExists && !params.overwrite) {
     return {
       created: false,
       path: skillFilePath,
@@ -356,6 +412,14 @@ export function createManagedSkill(
     };
   }
 
+  // An overwrite replaces the body and patches the frontmatter: a field the
+  // call leaves undefined keeps its current value, an explicit empty value
+  // clears it, and frontmatter the tool does not own passes through. Callers
+  // rarely hold every field (the retrospective sees a skill through a
+  // similarity hit; a user edit is "change step 3"), so a field they do not
+  // pass is kept rather than dropped.
+  const existing = skillExists ? readStoredManagedSkill(params.id) : null;
+
   // Resolve and validate every companion path before any write so an invalid
   // path leaves no partial files behind.
   const companionWrites: Array<{ resolvedPath: string; content: string }> = [];
@@ -411,6 +475,7 @@ export function createManagedSkill(
     activationHints: params.activationHints,
     avoidWhen: params.avoidWhen,
     category: params.category,
+    preserve: existing?.frontmatter,
   });
 
   mkdirSync(skillDir, { recursive: true });
@@ -450,6 +515,63 @@ export function createManagedSkill(
   return { created: true, path: skillFilePath };
 }
 
+/**
+ * A managed skill as it is on disk. Frontmatter fields come through the
+ * catalog's parser so they are exactly what routing and the Skills UI see;
+ * `body` is the stored text after the frontmatter, verbatim except for the
+ * separator newline the store writes before it and the trailing newline it
+ * guarantees. Verbatim matters: the skill loader substitutes `{baseDir}` and
+ * `{workspaceDir}` and strips feature-gated sections, and a caller that wrote
+ * that output back would bake absolute paths into the skill; and a first line
+ * that opens an indented code block must keep its indentation or a copy turns
+ * it into prose. `frontmatter` is the whole block as written, for an
+ * overwrite to carry keys through that the typed fields do not cover.
+ */
+export interface StoredManagedSkill {
+  name: string;
+  description: string;
+  frontmatter: Record<string, unknown>;
+  emoji?: string;
+  includes?: string[];
+  activationHints?: string[];
+  avoidWhen?: string[];
+  category?: string;
+  body: string;
+}
+
+/**
+ * Read a managed skill from disk. Best-effort: a missing file or frontmatter
+ * that does not parse resolves to null, so a caller enriching or patching one
+ * skill never fails on a bad one.
+ */
+export function readStoredManagedSkill(
+  skillId: string,
+): StoredManagedSkill | null {
+  const skillFilePath = join(getManagedSkillDir(skillId), "SKILL.md");
+  try {
+    const content = readFileSync(skillFilePath, "utf-8");
+    const parsed = parseFrontmatter(content, skillFilePath);
+    const raw = parseFrontmatterFields(content);
+    if (!parsed || !raw) {
+      return null;
+    }
+    return {
+      name: parsed.name,
+      description: parsed.description,
+      frontmatter: raw.fields,
+      emoji: parsed.emoji,
+      includes: parsed.includes,
+      activationHints: parsed.activationHints,
+      avoidWhen: parsed.avoidWhen,
+      category: parsed.category,
+      body: raw.body.replace(/^(?:\r?\n)+/, "").replace(/(?:\r?\n)+$/, ""),
+    };
+  } catch (err) {
+    log.warn({ err, skillFilePath }, "Could not read managed skill");
+    return null;
+  }
+}
+
 interface DeleteManagedSkillResult {
   deleted: boolean;
   error?: string;

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,211 @@ 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",
+      frontmatter: {},
+      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",
+      frontmatter: {},
+      body: "Do the user's thing.",
+    },
+    "clean-disk": {
+      name: "Clean Disk",
+      description: "Free up disk space",
+      frontmatter: {},
+      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,
     });
   }
 

package/src/tools/skills/resolve-execute-invocation.ts

@@ -0,0 +1,24 @@
+import { getTool } from "../registry.js";
+import { resolveToolInvocationAlias } from "../tool-name-aliases.js";
+import {
+  recoverSkillExecuteEnvelope,
+  resolveSkillExecuteInput,
+} from "./execute.js";
+
+export function resolveSkillExecuteInvocation(
+  input: Record<string, unknown>,
+  allowedToolNames?: ReadonlySet<string>,
+): { name: string; input: Record<string, unknown> } {
+  const envelope = recoverSkillExecuteEnvelope(input);
+  const rawToolName = typeof envelope.tool === "string" ? envelope.tool : "";
+  const innerSchema = rawToolName
+    ? getTool(rawToolName)?.input_schema
+    : undefined;
+  const rawToolInput = resolveSkillExecuteInput(envelope, innerSchema);
+
+  return resolveToolInvocationAlias(
+    rawToolName,
+    { ...rawToolInput },
+    allowedToolNames,
+  );
+}