@vellumai/assistant 0.5.16 → 0.6.0

package/src/skills/clawhub.ts

@@ -1,14 +1,13 @@
-import {
-  existsSync,
-  readdirSync,
-  readFileSync,
-  statSync,
-  writeFileSync,
-} from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
 import { getLogger } from "../util/logger.js";
 import { getWorkspaceSkillsDir } from "../util/platform.js";
+import {
+  computeSkillHash,
+  readInstallMeta,
+  writeInstallMeta,
+} from "./install-meta.js";
 
 const log = getLogger("clawhub");
 
@@ -54,61 +53,15 @@ export function loadIntegrityManifest(): IntegrityManifest {
   }
 }
 
-function saveIntegrityManifest(manifest: IntegrityManifest): void {
-  writeFileSync(
-    getIntegrityPath(),
-    JSON.stringify(manifest, null, 2) + "\n",
-    "utf-8",
-  );
-}
-
-/** Collect all file contents in a directory tree, sorted by relative path for determinism. */
-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) {
-    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).
- */
-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")}`;
-}
-
 /**
  * Record or verify the content hash of an installed skill.
  * On first install: stores the hash (trust-on-first-use).
  * On subsequent installs: compares with stored hash and warns on mismatch.
+ *
+ * Always writes to `install-meta.json`. For skills that don't have one yet,
+ * creates a new `install-meta.json` with minimal metadata. Reads from the
+ * legacy `.integrity.json` manifest as a read-only fallback for stored hashes
+ * from skills that haven't been migrated yet.
  */
 export function verifyAndRecordSkillHash(slug: string): void {
   const skillDir = join(getManagedSkillsDir(), slug);
@@ -118,17 +71,28 @@ export function verifyAndRecordSkillHash(slug: string): void {
     return;
   }
 
-  const manifest = loadIntegrityManifest();
-  const existing = manifest[slug];
+  // Try install-meta.json first for stored hash
+  const installMeta = readInstallMeta(skillDir);
+  let storedHash: string | undefined;
 
-  if (existing) {
-    const storedHash = existing.sha256;
+  if (installMeta?.contentHash) {
+    storedHash = installMeta.contentHash;
+  } else {
+    // Fall back to legacy .integrity.json manifest
+    const manifest = loadIntegrityManifest();
+    const existing = manifest[slug];
+    if (existing) {
+      storedHash =
+        typeof existing.sha256 === "string" ? existing.sha256 : undefined;
+    }
+  }
 
-    // Guard against corrupted manifest entries where sha256 is not a string
+  if (storedHash) {
+    // Guard against corrupted entries where hash is not a string
     if (typeof storedHash !== "string") {
       log.warn(
         { slug },
-        "Integrity manifest entry has non-string sha256 — re-recording hash",
+        "Stored hash has non-string value — re-recording hash",
       );
     } else if (!storedHash.startsWith("v2:")) {
       // Unknown format (not v2: prefix) — warn about integrity mismatch
@@ -155,9 +119,18 @@ export function verifyAndRecordSkillHash(slug: string): void {
     );
   }
 
-  // Always store the latest hash
-  manifest[slug] = { sha256: hash, installedAt: new Date().toISOString() };
-  saveIntegrityManifest(manifest);
+  // Write to install-meta.json (preferred). If no install-meta exists yet,
+  // create one with minimal metadata.
+  if (installMeta) {
+    writeInstallMeta(skillDir, { ...installMeta, contentHash: hash });
+  } else {
+    writeInstallMeta(skillDir, {
+      origin: "clawhub",
+      installedAt: new Date().toISOString(),
+      slug,
+      contentHash: hash,
+    });
+  }
 }
 
 interface ClawhubInstallResult {
@@ -248,7 +221,7 @@ async function runClawhub(
 
 export async function clawhubInstall(
   slug: string,
-  opts?: { version?: string },
+  opts?: { version?: string; contactId?: string },
 ): Promise<ClawhubInstallResult> {
   if (!validateSlug(slug)) {
     return { success: false, error: `Invalid skill slug: ${slug}` };
@@ -264,7 +237,19 @@ export async function clawhubInstall(
         result.stderr.trim() || result.stdout.trim() || "Unknown error";
       return { success: false, error };
     }
-    verifyAndRecordSkillHash(slug);
+
+    // Write install-meta.json for the installed skill.
+    // contentHash is included here, so there's no need to call
+    // verifyAndRecordSkillHash() — it would just rewrite the same data.
+    const skillDir = join(getManagedSkillsDir(), slug);
+    writeInstallMeta(skillDir, {
+      origin: "clawhub",
+      slug,
+      installedAt: new Date().toISOString(),
+      ...(opts?.contactId ? { installedBy: opts.contactId } : {}),
+      contentHash: computeSkillHash(skillDir) ?? undefined,
+    });
+
     return { success: true, skillName: slug };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -292,63 +277,63 @@ export async function clawhubUpdate(
 
 export async function clawhubSearch(
   query: string,
+  opts?: { limit?: number },
 ): Promise<ClawhubSearchResult> {
+  const limit = opts?.limit ?? 25;
+
   // Empty query: use explore (browse trending) instead of search
   if (!query.trim()) {
-    return clawhubExplore();
+    return clawhubExplore({ limit });
   }
 
+  const result = await runClawhub(["search", query, "--limit", String(limit)]);
+  if (result.exitCode !== 0) {
+    const error =
+      result.stderr.trim() || result.stdout.trim() || "Unknown error";
+    throw new Error(`clawhub search failed: ${error}`);
+  }
+  // Try JSON first
   try {
-    const result = await runClawhub(["search", query, "--limit", "25"]);
-    if (result.exitCode !== 0) {
-      return { skills: [] };
+    const parsed = JSON.parse(result.stdout);
+    if (Array.isArray(parsed)) {
+      return {
+        skills: parsed.map((s: ClawhubSearchResultItem) => ({
+          ...s,
+          source: s.source ?? ("clawhub" as const),
+        })),
+      };
     }
-    // Try JSON first
-    try {
-      const parsed = JSON.parse(result.stdout);
-      if (Array.isArray(parsed)) {
-        return {
-          skills: parsed.map((s: ClawhubSearchResultItem) => ({
-            ...s,
-            source: s.source ?? ("clawhub" as const),
-          })),
-        };
-      }
-      if (parsed.skills && Array.isArray(parsed.skills)) {
-        return {
-          skills: parsed.skills.map((s: ClawhubSearchResultItem) => ({
-            ...s,
-            source: s.source ?? ("clawhub" as const),
-          })),
-        };
-      }
-    } catch {
-      // CLI outputs text: "slug vVersion  DisplayName  (score)"
+    if (parsed.skills && Array.isArray(parsed.skills)) {
+      return {
+        skills: parsed.skills.map((s: ClawhubSearchResultItem) => ({
+          ...s,
+          source: s.source ?? ("clawhub" as const),
+        })),
+      };
     }
+  } catch {
+    // CLI outputs text: "slug vVersion  DisplayName  (score)"
+  }
 
-    // Parse text output lines: "slug vVersion  Display Name  (score)"
-    const skills: ClawhubSearchResultItem[] = [];
-    for (const line of result.stdout.split("\n")) {
-      const match = line.match(/^(\S+)\s+v(\S+)\s+(.+?)\s+\([\d.]+\)\s*$/);
-      if (match) {
-        skills.push({
-          slug: match[1],
-          version: match[2],
-          name: match[3].trim(),
-          description: "",
-          author: "",
-          stars: 0,
-          installs: 0,
-          createdAt: 0,
-          source: "clawhub",
-        });
-      }
+  // Parse text output lines: "slug vVersion  Display Name  (score)"
+  const skills: ClawhubSearchResultItem[] = [];
+  for (const line of result.stdout.split("\n")) {
+    const match = line.match(/^(\S+)\s+v(\S+)\s+(.+?)\s+\([\d.]+\)\s*$/);
+    if (match) {
+      skills.push({
+        slug: match[1],
+        version: match[2],
+        name: match[3].trim(),
+        description: "",
+        author: "",
+        stars: 0,
+        installs: 0,
+        createdAt: 0,
+        source: "clawhub",
+      });
     }
-    return { skills };
-  } catch (err) {
-    log.warn({ err }, "clawhub search failed");
-    return { skills: [] };
   }
+  return { skills };
 }
 
 export async function clawhubExplore(opts?: {
@@ -358,46 +343,41 @@ export async function clawhubExplore(opts?: {
   const limit = String(opts?.limit ?? 25);
   const sort = opts?.sort ?? "installsAllTime";
 
+  const result = await runClawhub([
+    "explore",
+    "--json",
+    "--limit",
+    limit,
+    "--sort",
+    sort,
+  ]);
+  if (result.exitCode !== 0) {
+    const error =
+      result.stderr.trim() || result.stdout.trim() || "Unknown error";
+    throw new Error(`clawhub explore failed: ${error}`);
+  }
   try {
-    const result = await runClawhub([
-      "explore",
-      "--json",
-      "--limit",
-      limit,
-      "--sort",
-      sort,
-    ]);
-    if (result.exitCode !== 0) {
-      return { skills: [] };
-    }
-    try {
-      const parsed = JSON.parse(result.stdout);
-      const items = parsed.items ?? parsed;
-      if (!Array.isArray(items)) return { skills: [] };
-
-      // Normalize explore response to ClawhubSearchResultItem shape
-      const skills: ClawhubSearchResultItem[] = items.map(
-        (item: Record<string, unknown>) => ({
-          name: (item.displayName as string) ?? (item.slug as string) ?? "",
-          slug: (item.slug as string) ?? "",
-          description: (item.summary as string) ?? "",
-          author: (item.author as string) ?? "",
-          stars: (item.stats as Record<string, number>)?.stars ?? 0,
-          installs:
-            (item.stats as Record<string, number>)?.installsAllTime ?? 0,
-          version: (item.tags as Record<string, string>)?.latest ?? "",
-          createdAt: (item.createdAt as number) ?? 0,
-          source: "clawhub",
-        }),
-      );
-      return { skills };
-    } catch {
-      // parse failure
-    }
-    return { skills: [] };
-  } catch (err) {
-    log.warn({ err }, "clawhub explore failed");
-    return { skills: [] };
+    const parsed = JSON.parse(result.stdout);
+    const items = parsed.items ?? parsed;
+    if (!Array.isArray(items)) return { skills: [] };
+
+    // Normalize explore response to ClawhubSearchResultItem shape
+    const skills: ClawhubSearchResultItem[] = items.map(
+      (item: Record<string, unknown>) => ({
+        name: (item.displayName as string) ?? (item.slug as string) ?? "",
+        slug: (item.slug as string) ?? "",
+        description: (item.summary as string) ?? "",
+        author: (item.author as string) ?? "",
+        stars: (item.stats as Record<string, number>)?.stars ?? 0,
+        installs: (item.stats as Record<string, number>)?.installsAllTime ?? 0,
+        version: (item.tags as Record<string, string>)?.latest ?? "",
+        createdAt: (item.createdAt as number) ?? 0,
+        source: "clawhub",
+      }),
+    );
+    return { skills };
+  } catch {
+    throw new Error("Failed to parse clawhub explore output");
   }
 }
 

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

@@ -13,6 +13,7 @@ import { stringify as stringifyYaml } from "yaml";
 
 import { getLogger } from "../util/logger.js";
 import { getWorkspaceSkillsDir } from "../util/platform.js";
+import { writeInstallMeta } from "./install-meta.js";
 import { deleteSkillCapabilityMemory } from "./skill-memory.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(