@vellumai/assistant 0.5.16 → 0.6.1

package/src/skills/install-meta.ts

@@ -0,0 +1,208 @@
+import { randomUUID } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+
+// ─── SkillInstallMeta type ──────────────────────────────────────────────────
+
+export interface SkillInstallMeta {
+  origin: "vellum" | "clawhub" | "skillssh" | "custom";
+  installedAt: string; // ISO 8601
+  installedBy?: string; // actorPrincipalId from auth context (identifies who initiated the install)
+  backfilledBy?: string; // set by migration that backfilled this file (e.g. "migration-026")
+  version?: string; // semver if known
+  slug?: string; // registry slug
+  sourceRepo?: string; // GitHub repo (e.g. "vercel-labs/agent-skills")
+  contentHash?: string; // SHA-256 content hash (v2:hex format)
+}
+
+// ─── Atomic write helper ────────────────────────────────────────────────────
+
+function atomicWriteFile(filePath: string, content: string): void {
+  const dir = dirname(filePath);
+  mkdirSync(dir, { recursive: true });
+  const tmpPath = join(dir, `.tmp-${randomUUID()}`);
+  writeFileSync(tmpPath, content, "utf-8");
+  renameSync(tmpPath, filePath);
+}
+
+// ─── Write install-meta.json ────────────────────────────────────────────────
+
+const INSTALL_META_FILENAME = "install-meta.json";
+const LEGACY_VERSION_FILENAME = "version.json";
+
+/**
+ * Atomically write `install-meta.json` inside the skill directory.
+ */
+export function writeInstallMeta(
+  skillDir: string,
+  meta: SkillInstallMeta,
+): void {
+  const filePath = join(skillDir, INSTALL_META_FILENAME);
+  atomicWriteFile(filePath, JSON.stringify(meta, null, 2) + "\n");
+}
+
+// ─── Read install-meta.json (with legacy fallback) ──────────────────────────
+
+/**
+ * Reads `install-meta.json` from the skill directory. If not found, falls
+ * back to reading legacy `version.json` and inferring the origin:
+ *
+ * - Has `origin: "skills.sh"` -> `origin: "skillssh"`, copies `source` as
+ *   `sourceRepo` and `skillSlug` as `slug`.
+ * - Has `version` but no `origin` field -> `origin: "vellum"`.
+ * - Otherwise -> `origin: "custom"`.
+ *
+ * Legacy files never have `installedBy`, so it will be `undefined` for
+ * backfilled skills.
+ *
+ * If neither file exists, returns `null`.
+ */
+export function readInstallMeta(skillDir: string): SkillInstallMeta | null {
+  // Try install-meta.json first
+  const metaPath = join(skillDir, INSTALL_META_FILENAME);
+  if (existsSync(metaPath)) {
+    try {
+      return JSON.parse(readFileSync(metaPath, "utf-8")) as SkillInstallMeta;
+    } catch {
+      // Malformed install-meta.json (partial write, manual edit, etc.) —
+      // fall through to the legacy version.json path so we don't lose
+      // provenance info when a valid legacy file exists.
+    }
+  }
+
+  // Fall back to legacy version.json
+  const legacyPath = join(skillDir, LEGACY_VERSION_FILENAME);
+  if (!existsSync(legacyPath)) {
+    return null;
+  }
+
+  try {
+    const raw = JSON.parse(readFileSync(legacyPath, "utf-8")) as Record<
+      string,
+      unknown
+    >;
+    return inferFromLegacyVersionJson(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Infer a SkillInstallMeta from a legacy version.json object.
+ */
+function inferFromLegacyVersionJson(
+  raw: Record<string, unknown>,
+): SkillInstallMeta {
+  // skills.sh origin: has `origin: "skills.sh"`
+  if (raw.origin === "skills.sh") {
+    return {
+      origin: "skillssh",
+      installedAt:
+        typeof raw.installedAt === "string"
+          ? raw.installedAt
+          : new Date().toISOString(),
+      sourceRepo: typeof raw.source === "string" ? raw.source : undefined,
+      slug: typeof raw.skillSlug === "string" ? raw.skillSlug : undefined,
+    };
+  }
+
+  // Vellum (first-party catalog) origin: has `version` but no `origin` field
+  if (typeof raw.version === "string" && !("origin" in raw)) {
+    return {
+      origin: "vellum",
+      installedAt:
+        typeof raw.installedAt === "string"
+          ? raw.installedAt
+          : new Date().toISOString(),
+      version: raw.version,
+    };
+  }
+
+  // Unknown format -> custom
+  return {
+    origin: "custom",
+    installedAt:
+      typeof raw.installedAt === "string"
+        ? raw.installedAt
+        : new Date().toISOString(),
+  };
+}
+
+// ─── Content hash computation ───────────────────────────────────────────────
+
+/**
+ * Metadata files excluded from content hashing. These are written by the
+ * installer and must not contribute to the content hash — otherwise the hash
+ * stored inside `install-meta.json` would change after writing the file.
+ */
+const METADATA_FILENAMES = new Set([
+  INSTALL_META_FILENAME, // install-meta.json
+  LEGACY_VERSION_FILENAME, // version.json
+]);
+
+/**
+ * Collect all file contents in a directory tree, sorted by relative path
+ * for determinism. Metadata files (`install-meta.json`, `version.json`) at
+ * the root level are excluded so the content hash covers only actual skill
+ * content.
+ */
+export function collectFileContents(
+  dir: string,
+  prefix = "",
+): Array<{ relPath: string; content: Buffer }> {
+  const results: Array<{ relPath: string; content: Buffer }> = [];
+  if (!existsSync(dir)) return results;
+
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    // Exclude metadata files at the root level (prefix === "").
+    // Only exclude actual files — a directory with a metadata name should
+    // still be traversed so nested content contributes to the hash.
+    if (!prefix && entry.isFile() && METADATA_FILENAMES.has(entry.name))
+      continue;
+
+    const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...collectFileContents(fullPath, relPath));
+    } else if (entry.isFile()) {
+      results.push({ relPath, content: readFileSync(fullPath) });
+    }
+  }
+  return results.sort((a, b) => a.relPath.localeCompare(b.relPath));
+}
+
+/**
+ * Compute a SHA-256 hash over all files in a skill directory.
+ * Returns format: "v2:sha256hex" (version prefix added to support hash format
+ * evolution).
+ *
+ * This is the content hash used by the integrity manifest (trust-on-first-use).
+ * It differs from `computeSkillVersionHash` in `version-hash.ts`, which uses a
+ * different hashing strategy (v1: prefix) for version identity.
+ */
+export function computeSkillHash(skillDir: string): string | null {
+  if (!existsSync(skillDir) || !statSync(skillDir).isDirectory()) return null;
+
+  const files = collectFileContents(skillDir);
+  if (files.length === 0) return null;
+
+  const hasher = new Bun.CryptoHasher("sha256");
+  for (const file of files) {
+    // Length-prefix each segment to prevent boundary ambiguity collisions
+    const pathBuf = Buffer.from(file.relPath, "utf-8");
+    hasher.update(`${pathBuf.length}:`);
+    hasher.update(pathBuf);
+    hasher.update(`${file.content.length}:`);
+    hasher.update(file.content);
+  }
+  return `v2:${hasher.digest("hex")}`;
+}

package/src/skills/managed-store.ts

@@ -11,9 +11,10 @@ import { dirname, join } from "node:path";
 
 import { stringify as stringifyYaml } from "yaml";
 
+import { deleteSkillCapabilityNode } from "../memory/graph/capability-seed.js";
 import { getLogger } from "../util/logger.js";
 import { getWorkspaceSkillsDir } from "../util/platform.js";
-import { deleteSkillCapabilityMemory } from "./skill-memory.js";
+import { writeInstallMeta } from "./install-meta.js";
 
 const log = getLogger("managed-store");
 
@@ -165,15 +166,20 @@ function getVersionMetaPath(id: string): string {
   return join(getManagedSkillDir(id), "version.json");
 }
 
-function writeVersionMeta(id: string, version: string): void {
-  const meta: SkillVersionMeta = {
-    version,
-    installedAt: new Date().toISOString(),
-  };
-  atomicWriteFile(getVersionMetaPath(id), JSON.stringify(meta, null, 2) + "\n");
-}
-
 export function readSkillVersion(id: string): string | null {
+  // Try install-meta.json first (new format)
+  const installMetaPath = join(getManagedSkillDir(id), "install-meta.json");
+  if (existsSync(installMetaPath)) {
+    try {
+      const raw = readFileSync(installMetaPath, "utf-8");
+      const meta = JSON.parse(raw) as { version?: string };
+      if (meta.version) return meta.version;
+    } catch {
+      // Fall through to legacy path
+    }
+  }
+
+  // Fall back to legacy version.json
   const metaPath = getVersionMetaPath(id);
   if (!existsSync(metaPath)) return null;
   try {
@@ -197,6 +203,7 @@ interface CreateManagedSkillParams {
   addToIndex?: boolean;
   includes?: string[];
   version?: string;
+  contactId?: string;
 }
 
 interface CreateManagedSkillResult {
@@ -259,14 +266,18 @@ export function createManagedSkill(
   mkdirSync(skillDir, { recursive: true });
   atomicWriteFile(skillFilePath, content);
 
-  if (params.version) {
-    writeVersionMeta(params.id, params.version);
-  } else {
-    // Remove stale version metadata when overwriting without a version
-    const metaPath = getVersionMetaPath(params.id);
-    if (existsSync(metaPath)) {
-      rmSync(metaPath);
-    }
+  // Write install metadata
+  writeInstallMeta(skillDir, {
+    origin: "custom",
+    installedAt: new Date().toISOString(),
+    ...(params.version ? { version: params.version } : {}),
+    ...(params.contactId ? { installedBy: params.contactId } : {}),
+  });
+
+  // Clean up legacy version.json if present (superseded by install-meta.json)
+  const metaPath = getVersionMetaPath(params.id);
+  if (existsSync(metaPath)) {
+    rmSync(metaPath);
   }
 
   log.info(
@@ -308,7 +319,7 @@ export function deleteManagedSkill(
   }
 
   rmSync(skillDir, { recursive: true });
-  deleteSkillCapabilityMemory(id);
+  deleteSkillCapabilityNode(id);
   log.info({ id, path: skillDir }, "Deleted managed skill");
 
   let indexUpdated = false;

package/src/skills/skill-memory.ts

@@ -1,16 +1,5 @@
-import { and, eq } from "drizzle-orm";
-import { v4 as uuid } from "uuid";
-
-import { getConfig } from "../config/loader.js";
-import { resolveSkillStates } from "../config/skill-state.js";
-import { loadSkillCatalog, type SkillSummary } from "../config/skills.js";
-import { getDb } from "../memory/db.js";
-import { computeMemoryFingerprint } from "../memory/fingerprint.js";
-import { enqueueMemoryJob } from "../memory/jobs-store.js";
-import { memoryItems } from "../memory/schema.js";
-import { getLogger } from "../util/logger.js";
-
-const log = getLogger("skill-memory");
+import type { SkillSummary } from "../config/skills.js";
+import type { CatalogSkill } from "./catalog-install.js";
 
 /**
  * Generic input for building capability statements.
@@ -40,222 +29,16 @@ export function fromSkillSummary(entry: SkillSummary): SkillCapabilityInput {
 }
 
 /**
- * Build a semantically rich capability statement from a skill capability input.
- * Truncated to 500 chars max (matching the limit used by memory item extraction).
- */
-export function buildCapabilityStatement(input: SkillCapabilityInput): string {
-  const { displayName, activationHints, avoidWhen } = input;
-
-  let statement = `The "${displayName}" skill (${input.id}) is available. ${input.description}.`;
-  if (activationHints && activationHints.length > 0) {
-    statement += ` Use when: ${activationHints.join("; ")}.`;
-  }
-  if (avoidWhen && avoidWhen.length > 0) {
-    statement += ` Avoid when: ${avoidWhen.join("; ")}.`;
-  }
-
-  // Truncate to 500 chars max
-  if (statement.length > 500) {
-    statement = statement.slice(0, 500);
-  }
-
-  return statement;
-}
-
-/**
- * Upsert a capability memory item for a skill.
- * Best-effort: errors are logged but never thrown.
- */
-export function upsertSkillCapabilityMemory(
-  skillId: string,
-  input: SkillCapabilityInput,
-): void {
-  try {
-    const db = getDb();
-    const subject = `skill:${skillId}`;
-    const statement = buildCapabilityStatement(input);
-    const kind = "capability";
-    const scopeId = "default";
-    const confidence = 1.0;
-    const importance = 0.7;
-    const fingerprint = computeMemoryFingerprint(
-      scopeId,
-      kind,
-      subject,
-      statement,
-    );
-    const now = Date.now();
-
-    const existing = db
-      .select()
-      .from(memoryItems)
-      .where(
-        and(
-          eq(memoryItems.kind, kind),
-          eq(memoryItems.subject, subject),
-          eq(memoryItems.scopeId, scopeId),
-        ),
-      )
-      .get();
-
-    if (existing) {
-      if (
-        existing.status === "active" &&
-        existing.fingerprint === fingerprint
-      ) {
-        // Same content — just touch lastSeenAt
-        db.update(memoryItems)
-          .set({ lastSeenAt: now })
-          .where(eq(memoryItems.id, existing.id))
-          .run();
-        return;
-      }
-
-      if (existing.status === "active") {
-        // Content changed — update statement and fingerprint
-        db.update(memoryItems)
-          .set({
-            statement,
-            fingerprint,
-            lastSeenAt: now,
-          })
-          .where(eq(memoryItems.id, existing.id))
-          .run();
-        enqueueMemoryJob("embed_item", { itemId: existing.id });
-        return;
-      }
-
-      // status === "deleted" or other — reactivate
-      db.update(memoryItems)
-        .set({
-          status: "active",
-          statement,
-          fingerprint,
-          lastSeenAt: now,
-          firstSeenAt: now,
-        })
-        .where(eq(memoryItems.id, existing.id))
-        .run();
-      enqueueMemoryJob("embed_item", { itemId: existing.id });
-      return;
-    }
-
-    // No existing — insert new row
-    const id = uuid();
-    db.insert(memoryItems)
-      .values({
-        id,
-        kind,
-        subject,
-        statement,
-        status: "active",
-        confidence,
-        importance,
-        fingerprint,
-        sourceType: "extraction",
-        scopeId,
-        firstSeenAt: now,
-        lastSeenAt: now,
-      })
-      .run();
-    enqueueMemoryJob("embed_item", { itemId: id });
-  } catch (err) {
-    log.warn({ err, skillId }, "Failed to upsert skill capability memory");
-  }
-}
-
-/**
- * Soft-delete the capability memory item for a skill.
- * Best-effort: errors are logged but never thrown.
+ * Convert a CatalogSkill to a SkillCapabilityInput.
+ * CatalogSkill stores display-name and hints inside nested metadata.
  */
-export function deleteSkillCapabilityMemory(skillId: string): void {
-  try {
-    const db = getDb();
-    const subject = `skill:${skillId}`;
-    const now = Date.now();
-
-    const existing = db
-      .select()
-      .from(memoryItems)
-      .where(
-        and(
-          eq(memoryItems.kind, "capability"),
-          eq(memoryItems.subject, subject),
-          eq(memoryItems.scopeId, "default"),
-        ),
-      )
-      .get();
-
-    if (existing && existing.status !== "deleted") {
-      db.update(memoryItems)
-        .set({ status: "deleted", lastSeenAt: now })
-        .where(eq(memoryItems.id, existing.id))
-        .run();
-    }
-  } catch (err) {
-    log.warn({ err, skillId }, "Failed to delete skill capability memory");
-  }
+export function fromCatalogSkill(entry: CatalogSkill): SkillCapabilityInput {
+  return {
+    id: entry.id,
+    displayName: entry.metadata?.vellum?.["display-name"] ?? entry.name,
+    description: entry.description,
+    activationHints: entry.metadata?.vellum?.["activation-hints"],
+    avoidWhen: entry.metadata?.vellum?.["avoid-when"],
+  };
 }
 
-/**
- * Seed capability memory items for all enabled skills (bundled, managed, workspace, extra).
- * Prunes stale entries whose skills are no longer in the enabled set.
- * Best-effort: errors are logged but never thrown.
- */
-export function seedCatalogSkillMemories(): void {
-  try {
-    const catalog = loadSkillCatalog();
-    const config = getConfig();
-    const resolved = resolveSkillStates(catalog, config);
-    const enabled = resolved.filter((r) => r.state === "enabled");
-
-    const catalogIds = new Set<string>();
-    for (const { summary } of enabled) {
-      catalogIds.add(summary.id);
-      const input = fromSkillSummary(summary);
-
-      // Enrich mcp-setup description with configured server names
-      if (summary.id === "mcp-setup") {
-        const servers = config.mcp?.servers;
-        if (servers) {
-          const names = Object.keys(servers).filter(
-            (name) => servers[name]?.enabled !== false,
-          );
-          if (names.length > 0) {
-            input.description += ` Configured: ${names.join(", ")}`;
-          }
-        }
-      }
-
-      upsertSkillCapabilityMemory(summary.id, input);
-    }
-
-    // Prune stale capability memories for skills no longer in the enabled set
-    const db = getDb();
-    const allCapabilities = db
-      .select()
-      .from(memoryItems)
-      .where(
-        and(
-          eq(memoryItems.kind, "capability"),
-          eq(memoryItems.scopeId, "default"),
-          eq(memoryItems.status, "active"),
-        ),
-      )
-      .all();
-
-    const now = Date.now();
-    for (const item of allCapabilities) {
-      if (!item.subject.startsWith("skill:")) continue;
-      const itemSkillId = item.subject.replace("skill:", "");
-      if (!catalogIds.has(itemSkillId)) {
-        db.update(memoryItems)
-          .set({ status: "deleted", lastSeenAt: now })
-          .where(eq(memoryItems.id, item.id))
-          .run();
-      }
-    }
-  } catch (err) {
-    log.warn({ err }, "Failed to seed catalog skill memories");
-  }
-}

package/src/skills/skillssh-registry.ts

@@ -5,6 +5,7 @@ import { dirname, join, resolve, sep } from "node:path";
 
 import { getWorkspaceSkillsDir } from "../util/platform.js";
 import { upsertSkillsIndex } from "./catalog-install.js";
+import { computeSkillHash, writeInstallMeta } from "./install-meta.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -434,9 +435,12 @@ export function validateSkillSlug(slug: string): void {
  * 1. Validates the skill slug for path safety
  * 2. Fetches all files from `skills/<skillSlug>/` in the source repo
  * 3. Writes them to `<workspace>/skills/<skillSlug>/` with path traversal protection
- * 4. Writes `version.json` with origin metadata
- * 5. Runs `bun install` if a `package.json` is present
- * 6. Registers the skill in SKILLS.md only after all steps succeed
+ * 4. Writes `install-meta.json` with origin metadata
+ * 5. Installs npm dependencies (if package.json exists)
+ * 6. Updates SKILLS.md index
+ *
+ * Auto-enable and memory seeding are handled by the caller (e.g.
+ * `postInstallSkill()` in the daemon, or left to the user for CLI installs).
  */
 export async function installExternalSkill(
   owner: string,
@@ -444,6 +448,7 @@ export async function installExternalSkill(
   skillSlug: string,
   overwrite: boolean,
   ref?: string,
+  contactId?: string,
 ): Promise<void> {
   // Validate slug before using in filesystem paths
   validateSkillSlug(skillSlug);
@@ -480,20 +485,19 @@ export async function installExternalSkill(
     writeFileSync(destPath, content, "utf-8");
   }
 
-  // Write origin metadata
-  const meta = {
-    origin: "skills.sh",
-    source: `${owner}/${repo}`,
-    skillSlug,
+  // Write install metadata
+  writeInstallMeta(skillDir, {
+    origin: "skillssh",
+    slug: skillSlug,
+    sourceRepo: `${owner}/${repo}`,
     installedAt: new Date().toISOString(),
-  };
-  writeFileSync(
-    join(skillDir, "version.json"),
-    JSON.stringify(meta, null, 2) + "\n",
-    "utf-8",
-  );
+    ...(contactId ? { installedBy: contactId } : {}),
+    contentHash: computeSkillHash(skillDir) ?? undefined,
+  });
 
-  // Install npm dependencies if the skill ships a package.json
+  // Post-install: install dependencies first, then index the skill.
+  // Running bun install before upsertSkillsIndex ensures we don't index a
+  // skill whose dependencies failed to install.
   if (existsSync(join(skillDir, "package.json"))) {
     const bunPath = `${homedir()}/.bun/bin`;
     execSync("bun install", {
@@ -502,7 +506,5 @@ export async function installExternalSkill(
       env: { ...process.env, PATH: `${bunPath}:${process.env.PATH}` },
     });
   }
-
-  // Register in SKILLS.md only after files are written and deps installed
   upsertSkillsIndex(skillSlug);
 }

package/src/subagent/index.ts

@@ -1,6 +1,16 @@
-export { SubagentManager } from "./manager.js";
-export type { SubagentConfig, SubagentState, SubagentStatus } from "./types.js";
-export { SUBAGENT_LIMITS, TERMINAL_STATUSES } from "./types.js";
+export { mergeSkillIds, SubagentManager } from "./manager.js";
+export type {
+  SubagentConfig,
+  SubagentRole,
+  SubagentRoleConfig,
+  SubagentState,
+  SubagentStatus,
+} from "./types.js";
+export {
+  SUBAGENT_LIMITS,
+  SUBAGENT_ROLE_REGISTRY,
+  TERMINAL_STATUSES,
+} from "./types.js";
 
 import { SubagentManager } from "./manager.js";