@botbotgo/agent-harness 0.0.16 → 0.0.17

package/dist/runtime/inventory.d.ts

@@ -6,6 +6,11 @@ export type InventoryToolRecord = {
 export type InventorySkillRecord = {
     name: string;
     path: string;
+    description?: string;
+    license?: string;
+    compatibility?: string;
+    metadata?: Record<string, string>;
+    allowedTools?: string[];
 };
 export type InventoryAgentRecord = {
     id: string;

package/dist/runtime/inventory.js

@@ -1,4 +1,4 @@
-import { readSkillName } from "./support/skill-metadata.js";
+import { readSkillMetadata } from "./support/skill-metadata.js";
 function listHostBindings(workspace) {
     return Array.from(workspace.bindings.values()).filter((binding) => binding.harnessRuntime.hostFacing);
 }
@@ -13,10 +13,18 @@ function dedupeTools(tools) {
     return Array.from(deduped.values());
 }
 function toSkillRecords(skillPaths) {
-    return Array.from(new Set(skillPaths)).map((skillPath) => ({
-        name: readSkillName(skillPath),
-        path: skillPath,
-    }));
+    return Array.from(new Set(skillPaths)).map((skillPath) => {
+        const metadata = readSkillMetadata(skillPath);
+        return {
+            name: metadata.name,
+            path: skillPath,
+            description: metadata.description,
+            license: metadata.license,
+            compatibility: metadata.compatibility,
+            metadata: metadata.metadata,
+            allowedTools: metadata.allowedTools,
+        };
+    });
 }
 export function listAgentTools(workspace, agentId) {
     const binding = findAgentBinding(workspace, agentId);

package/dist/runtime/support/skill-metadata.d.ts

@@ -1 +1,11 @@
+export type SkillMetadata = {
+    name: string;
+    description?: string;
+    license?: string;
+    compatibility?: string;
+    metadata?: Record<string, string>;
+    allowedTools?: string[];
+};
+export declare function readSkillMetadata(skillPath: string): SkillMetadata;
+export declare function validateSkillMetadata(skillPath: string): SkillMetadata;
 export declare function readSkillName(skillPath: string): string;

package/dist/runtime/support/skill-metadata.js

@@ -1,34 +1,147 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
-const skillNameCache = new Map();
-function parseFrontmatterName(document) {
+import { parse } from "yaml";
+const skillMetadataCache = new Map();
+const skillValidationCache = new Map();
+const SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function parseFrontmatterSource(document) {
     const match = document.match(/^---\s*\n([\s\S]*?)\n---\s*(?:\n|$)/);
-    if (!match) {
+    return match?.[1];
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeMetadata(value, strict) {
+    if (value === undefined) {
         return undefined;
     }
-    const nameLine = match[1]
-        .split("\n")
-        .map((line) => line.trim())
-        .find((line) => line.startsWith("name:"));
-    if (!nameLine) {
+    if (!isRecord(value)) {
+        if (strict) {
+            throw new Error("metadata must be a string key-value map");
+        }
         return undefined;
     }
-    const value = nameLine.slice("name:".length).trim().replace(/^["']|["']$/g, "");
-    return value || undefined;
+    const normalized = Object.entries(value).reduce((acc, [key, item]) => {
+        if (typeof item === "string") {
+            acc[key] = item;
+        }
+        return acc;
+    }, {});
+    if (strict && Object.keys(normalized).length !== Object.keys(value).length) {
+        throw new Error("metadata values must all be strings");
+    }
+    return Object.keys(normalized).length > 0 ? normalized : undefined;
 }
-export function readSkillName(skillPath) {
-    const cached = skillNameCache.get(skillPath);
+function toAllowedTools(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const tools = value.split(/\s+/).filter(Boolean);
+    return tools.length > 0 ? tools : undefined;
+}
+function parseFrontmatter(document, strict = false) {
+    const source = parseFrontmatterSource(document);
+    if (!source) {
+        return undefined;
+    }
+    const parsed = parse(source);
+    if (!isRecord(parsed)) {
+        return undefined;
+    }
+    return {
+        name: typeof parsed.name === "string" ? parsed.name : "",
+        description: typeof parsed.description === "string" ? parsed.description : undefined,
+        license: typeof parsed.license === "string" ? parsed.license : undefined,
+        compatibility: typeof parsed.compatibility === "string" ? parsed.compatibility : undefined,
+        metadata: normalizeMetadata(parsed.metadata, strict),
+        allowedTools: toAllowedTools(parsed["allowed-tools"]),
+    };
+}
+function isLegacyBuiltinSkillName(name) {
+    return /^builtin\.[a-z0-9-]+$/.test(name);
+}
+function validateSkillName(name, skillPath) {
+    if (!name || name.length > 64) {
+        throw new Error(`Skill ${skillPath} must define a name between 1 and 64 characters`);
+    }
+    if (!SKILL_NAME_PATTERN.test(name) && !isLegacyBuiltinSkillName(name)) {
+        throw new Error(`Skill ${skillPath} has invalid name ${name}. Standard skill names must use lowercase letters, numbers, and single hyphens`);
+    }
+    if (SKILL_NAME_PATTERN.test(name) && path.basename(skillPath) !== name) {
+        throw new Error(`Skill ${skillPath} must use a directory name that matches its frontmatter name ${name}`);
+    }
+}
+function validateSkillDescription(description, skillPath) {
+    if (!description || !description.trim() || description.length > 1024) {
+        throw new Error(`Skill ${skillPath} must define a description between 1 and 1024 characters`);
+    }
+}
+function validateCompatibility(value, skillPath) {
+    if (value !== undefined && (!value.trim() || value.length > 500)) {
+        throw new Error(`Skill ${skillPath} compatibility must be between 1 and 500 characters when provided`);
+    }
+}
+function validateMetadata(metadata, skillPath) {
+    if (!metadata) {
+        return;
+    }
+    if (Object.keys(metadata).length === 0) {
+        throw new Error(`Skill ${skillPath} metadata must contain string key-value pairs when provided`);
+    }
+}
+function parseSkillMetadataFromDocument(document, skillPath, strict) {
+    const parsed = parseFrontmatter(document, strict);
+    if (!parsed) {
+        if (strict) {
+            throw new Error(`Skill ${skillPath} must contain YAML frontmatter in SKILL.md`);
+        }
+        return { name: path.basename(skillPath) };
+    }
+    const metadata = {
+        name: strict ? parsed.name : parsed.name || path.basename(skillPath),
+        description: parsed.description,
+        license: parsed.license,
+        compatibility: parsed.compatibility,
+        metadata: parsed.metadata,
+        allowedTools: parsed.allowedTools,
+    };
+    if (strict) {
+        validateSkillName(metadata.name, skillPath);
+        validateSkillDescription(metadata.description, skillPath);
+        validateCompatibility(metadata.compatibility, skillPath);
+        validateMetadata(metadata.metadata, skillPath);
+    }
+    return metadata;
+}
+export function readSkillMetadata(skillPath) {
+    const cached = skillMetadataCache.get(skillPath);
     if (cached) {
         return cached;
     }
-    let resolvedName = path.basename(skillPath);
+    const metadata = {
+        name: path.basename(skillPath),
+    };
     try {
         const document = readFileSync(path.join(skillPath, "SKILL.md"), "utf8");
-        resolvedName = parseFrontmatterName(document) ?? resolvedName;
+        Object.assign(metadata, parseSkillMetadataFromDocument(document, skillPath, false));
     }
     catch {
         // Fall back to the directory name when the skill doc cannot be read.
     }
-    skillNameCache.set(skillPath, resolvedName);
-    return resolvedName;
+    skillMetadataCache.set(skillPath, metadata);
+    return metadata;
+}
+export function validateSkillMetadata(skillPath) {
+    const cached = skillValidationCache.get(skillPath);
+    if (cached) {
+        return cached;
+    }
+    const document = readFileSync(path.join(skillPath, "SKILL.md"), "utf8");
+    const metadata = parseSkillMetadataFromDocument(document, skillPath, true);
+    skillValidationCache.set(skillPath, metadata);
+    skillMetadataCache.set(skillPath, metadata);
+    return metadata;
+}
+export function readSkillName(skillPath) {
+    return readSkillMetadata(skillPath).name;
 }

package/dist/workspace/support/discovery.js

@@ -1,6 +1,7 @@
 import { existsSync, readdirSync, statSync } from "node:fs";
 import path from "node:path";
 import { defaultResourceConfigRoot, defaultResourceSkillsRoot } from "../../resource/resource.js";
+import { validateSkillMetadata } from "../../runtime/support/skill-metadata.js";
 import { ensureExternalResourceSource, isDirectoryPath, isExternalSourceLocator, resolveExternalResourcePath, resolveResourcePackageRoot, } from "../../resource/sources.js";
 import { parseAgentItem, readYamlItems } from "../object-loader.js";
 function resolveBuiltinPath(kind, ref) {
@@ -93,6 +94,7 @@ export function discoverSkillPaths(rootRefs, workspaceRoot) {
             throw new Error(`Skill discovery root ${rootRef} does not exist`);
         }
         if (existsSync(path.join(root, "SKILL.md"))) {
+            validateSkillMetadata(root);
             discovered.set(path.basename(root), root);
             continue;
         }
@@ -102,6 +104,7 @@ export function discoverSkillPaths(rootRefs, workspaceRoot) {
             }
             const skillRoot = path.join(root, entry.name);
             if (existsSync(path.join(skillRoot, "SKILL.md"))) {
+                validateSkillMetadata(skillRoot);
                 discovered.set(entry.name, skillRoot);
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.16",
+  "version": "0.0.17",
   "description": "Agent Harness framework package",
   "type": "module",
   "packageManager": "npm@10.9.2",