agentera 3.0.0-dev.4 → 3.0.0-dev.46

package/dist/validate/capability.js

@@ -1,7 +1,16 @@
 import fs from "node:fs";
 import path from "node:path";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
 import { loadYamlMapping } from "../core/yaml.js";
 import { loadCapabilitySchemaContract, } from "../registries/capabilityContract.js";
+/**
+ * Validate a capability directory against the capability schema contract.
+ * Faithful TS port of scripts/validate_capability.py.
+ *
+ * Note: YAML integer keys (`1:`) parse to JS string keys ("1"); numeric-key
+ * detection uses a digit regex, which matches Python's `isinstance(key, int)`
+ * for all real (bare-integer) schema keys.
+ */
 export const PROTOCOL_GROUPS = [
     "CONFIDENCE_SCALE",
     "SEVERITY_FINDING",
@@ -41,13 +50,13 @@ function pyListRepr(values) {
     return "[" + values.map((v) => `'${v}'`).join(", ") + "]";
 }
 export function loadContract(contractPath) {
-    return loadYamlMapping(fs.readFileSync(contractPath, "utf8"));
+    return loadYamlMapping(fs.readFileSync(contractPath, "utf8")); // cast: YAML parse IO boundary
 }
 export function loadSchemaFile(p) {
-    return loadYamlMapping(fs.readFileSync(p, "utf8"));
+    return loadYamlMapping(fs.readFileSync(p, "utf8")); // cast: YAML parse IO boundary
 }
 export function loadProtocol(protocolPath) {
-    return loadYamlMapping(fs.readFileSync(protocolPath, "utf8"));
+    return loadYamlMapping(fs.readFileSync(protocolPath, "utf8")); // cast: YAML parse IO boundary
 }
 function listSchemaFiles(schemasDir, glob) {
     // Agentera schema globs are always "*.yaml"; match on suffix.
@@ -71,7 +80,7 @@ export function collectSchemaGroups(schemasDir, requiredGroups, schemaGlob = "*.
                     combined[groupName] = {};
                 }
                 if (isMapping(groupData)) {
-                    Object.assign(combined[groupName], groupData);
+                    Object.assign(combined[groupName], groupData); // cast: parsed schema IO data
                 }
             }
         }
@@ -81,11 +90,18 @@ export function collectSchemaGroups(schemasDir, requiredGroups, schemaGlob = "*.
 export function checkDirectoryStructure(capDir, contract) {
     const errors = [];
     const directoryRules = contract.directoryRules;
-    const prose = path.join(capDir, directoryRules.instructionPath);
     const schemas = path.join(capDir, directoryRules.schemasPath);
-    const isFile = fs.existsSync(prose) && fs.statSync(prose).isFile();
+    // The instruction module path is a repo-relative path under
+    // packages/cli/src/capabilities/<name>/instructions.ts (D65). Resolve the
+    // capability name from the capDir (last path segment) and look up the
+    // module against the resolved Agentera source root, not the capDir.
+    const capabilityName = path.basename(capDir);
+    const instructionModulePath = (directoryRules.instructionModulePath ?? directoryRules.instructionPath).replace(/<name>/g, capabilityName);
+    const sourceRoot = resolveSourceRoot();
+    const instructionModuleAbs = path.join(sourceRoot, instructionModulePath);
+    const isFile = fs.existsSync(instructionModuleAbs) && fs.statSync(instructionModuleAbs).isFile();
     if (!isFile) {
-        errors.push(`V1 [error]: ${directoryRules.instructionPath} not found in ${capDir}`);
+        errors.push(`V1 [error]: ${instructionModulePath} not found in ${capDir}`);
     }
     const isDir = fs.existsSync(schemas) && fs.statSync(schemas).isDirectory();
     if (!isDir) {
@@ -165,13 +181,125 @@ export function checkTriggerPriorities(groups, sourceLabel, contract) {
         if (priority === null && priorityRules.required) {
             errors.push(`V5b [error]: TRIGGERS entry ${key} in ${sourceLabel} missing 'priority'`);
         }
-        else if (priority !== null && !priorityRules.allowedValues.includes(priority)) {
+        else if (priority !== null && !priorityRules.allowedValues.includes(priority)) { // cast: parsed schema IO data
             errors.push(`V5b [error]: TRIGGERS entry ${key} in ${sourceLabel} has invalid priority=${valueRepr(priority)} ` +
                 `(must be one of: ${priorityRules.allowedValues.join(", ")})`);
         }
     }
     return errors;
 }
+/**
+ * V7 trigger-entry enrichment validation. Enforces the four optional fields
+ * declared in TRIGGER_ENRICHMENT in capability_schema_contract.yaml. Every
+ * field is OPTIONAL; a triggers.yaml entry that omits all compatibility fields
+ * passes. The hybrid route contract limits these fields to the semantic phase
+ * after deterministic abstention while this validator preserves legacy
+ * enriched-file compatibility. Error messages include the
+ * valid range/value and the offending entry ID so authors can locate the
+ * violation without grepping the contract.
+ */
+export function checkTriggerEnrichment(groups, sourceLabel, contract) {
+    const errors = [];
+    const triggers = groups.TRIGGERS ?? {};
+    if (!isMapping(triggers)) {
+        return errors;
+    }
+    const enrichment = contract.triggerEnrichment;
+    const confidenceField = enrichment.fields.confidence_threshold;
+    const borderlineField = enrichment.fields.borderline_band;
+    const allowedIds = enrichment.allowedCapabilityIds;
+    for (const [key, entry] of Object.entries(triggers)) {
+        if (!isMapping(entry)) {
+            continue;
+        }
+        const entryId = entry.id ?? key;
+        const location = `TRIGGERS entry ${key} (${entryId}) in ${sourceLabel}`;
+        if (entry.patterns !== undefined) {
+            const value = entry.patterns;
+            if (!Array.isArray(value) || !value.every((pattern) => typeof pattern === "string")) {
+                errors.push(`V7 [error]: ${location} has patterns=${valueRepr(value)} ` +
+                    `(must be a list of strings)`);
+            }
+        }
+        if (entry.confidence_threshold !== undefined) {
+            const value = entry.confidence_threshold;
+            const min = confidenceField.min ?? 0;
+            const max = confidenceField.max ?? 100;
+            if (typeof value !== "number" ||
+                !Number.isInteger(value) ||
+                value < min ||
+                value > max) {
+                errors.push(`V7 [error]: ${location} has confidence_threshold=${valueRepr(value)} ` +
+                    `(must be an integer in range ${min}..${max})`);
+            }
+        }
+        if (entry.borderline_band !== undefined) {
+            const value = entry.borderline_band;
+            const min = borderlineField.min ?? 0;
+            const max = borderlineField.max ?? 100;
+            if (typeof value !== "number" ||
+                !Number.isInteger(value) ||
+                value < min ||
+                value > max) {
+                errors.push(`V7 [error]: ${location} has borderline_band=${valueRepr(value)} ` +
+                    `(must be an integer in range ${min}..${max})`);
+            }
+        }
+        if (entry.patterns_regex !== undefined) {
+            const value = entry.patterns_regex;
+            if (!Array.isArray(value)) {
+                errors.push(`V7 [error]: ${location} has patterns_regex=${valueRepr(value)} ` +
+                    `(must be a list of regex strings)`);
+            }
+            else {
+                for (let i = 0; i < value.length; i++) {
+                    const pattern = value[i];
+                    if (typeof pattern !== "string") {
+                        errors.push(`V7 [error]: ${location} patterns_regex[${i}] is not a string`);
+                        continue;
+                    }
+                    try {
+                        new RegExp(pattern);
+                    }
+                    catch {
+                        errors.push(`V7 [error]: ${location} patterns_regex[${i}]=${valueRepr(pattern)} ` +
+                            `is not a valid regular expression`);
+                    }
+                }
+            }
+        }
+        if (entry.disambiguates_against !== undefined) {
+            const value = entry.disambiguates_against;
+            if (!Array.isArray(value)) {
+                errors.push(`V7 [error]: ${location} has disambiguates_against=${valueRepr(value)} ` +
+                    `(must be a list of mappings each with 'capability' and 'hint')`);
+                continue;
+            }
+            for (let i = 0; i < value.length; i++) {
+                const item = value[i];
+                if (!isMapping(item)) {
+                    errors.push(`V7 [error]: ${location} disambiguates_against[${i}] must be a mapping with 'capability' and 'hint'`);
+                    continue;
+                }
+                const capability = item.capability;
+                if (typeof capability !== "string" || !capability) {
+                    errors.push(`V7 [error]: ${location} disambiguates_against[${i}] missing 'capability' ` +
+                        `(must be one of: ${allowedIds.join(", ")})`);
+                }
+                else if (!allowedIds.includes(capability)) {
+                    errors.push(`V7 [error]: ${location} disambiguates_against[${i}].capability=${valueRepr(capability)} ` +
+                        `is not a canonical capability ID (must be one of: ${allowedIds.join(", ")})`);
+                }
+                const hint = item.hint;
+                if (typeof hint !== "string" || hint.trim() === "") {
+                    errors.push(`V7 [error]: ${location} disambiguates_against[${i}] missing or empty 'hint' ` +
+                        `(must be a non-empty string distinguishing this trigger from the named capability)`);
+                }
+            }
+        }
+    }
+    return errors;
+}
 export function checkDeprecation(groups, sourceLabel, contract) {
     const warnings = [];
     const markerField = contract.deprecationRules.marker_field;
@@ -225,6 +353,7 @@ export function validateContractSelf(contractPath) {
     errors.push(...checkNumberedEntries(groups, contractPath, contract));
     errors.push(...checkStableIds(groups, contractPath, contract));
     errors.push(...checkTriggerPriorities(groups, contractPath, contract));
+    errors.push(...checkTriggerEnrichment(groups, contractPath, contract));
     for (const w of checkDeprecation(groups, contractPath, contract)) {
         process.stderr.write(w + "\n");
     }
@@ -241,6 +370,7 @@ export function validateCapability(capDir, contractPath) {
         allErrors.push(...checkNumberedEntries(groups, capDir, contract));
         allErrors.push(...checkStableIds(groups, capDir, contract));
         allErrors.push(...checkTriggerPriorities(groups, capDir, contract));
+        allErrors.push(...checkTriggerEnrichment(groups, capDir, contract));
         for (const w of checkDeprecation(groups, capDir, contract)) {
             process.stderr.write(w + "\n");
         }
@@ -260,7 +390,7 @@ export function buildProtocolValueLookup(protocolData) {
                 continue;
             }
             if ("value" in entry) {
-                values.add(entry.value);
+                values.add(entry.value); // cast: parsed protocol IO data
             }
         }
         if (values.size > 0) {
@@ -282,7 +412,7 @@ export function checkProtocolStructure(protocolData, sourceLabel) {
             errors.push(`[error]: group ${groupName} missing in ${sourceLabel}`);
             continue;
         }
-        const expectedPrefix = prefixes[groupName] ?? "";
+        const expectedPrefix = (prefixes[groupName] ?? ""); // cast: parsed protocol IO data
         const validIds = new Set();
         for (const [key, entry] of Object.entries(group)) {
             if (!isNumericKey(key)) {
@@ -314,7 +444,7 @@ export function checkProtocolStructure(protocolData, sourceLabel) {
                     errors.push(`[warning]: entry ${key} (${entry.id ?? "?"}) ` +
                         `in ${groupName} is deprecated but has no replaced_by`);
                 }
-                else if (!validIds.has(replaced)) {
+                else if (!validIds.has(replaced)) { // cast: parsed protocol IO data
                     errors.push(`[warning]: entry ${key} (${entry.id ?? "?"}) ` +
                         `in ${groupName} has replaced_by=${valueRepr(replaced)} ` +
                         `which does not match any entry ID`);
@@ -334,14 +464,14 @@ export function checkPhaseTransitions(protocolData, sourceLabel) {
     const phaseValues = new Set();
     for (const [key, entry] of Object.entries(phasesGroup)) {
         if (isNumericKey(key) && isMapping(entry) && "value" in entry) {
-            phaseValues.add(entry.value);
+            phaseValues.add(entry.value); // cast: parsed protocol IO data
         }
     }
     for (const [key, entry] of Object.entries(phasesGroup)) {
         if (!isNumericKey(key) || !isMapping(entry)) {
             continue;
         }
-        const successors = entry.valid_successors ?? [];
+        const successors = (entry.valid_successors ?? []); // cast: parsed protocol IO data
         const entryId = entry.id ?? `entry ${key}`;
         for (const s of successors) {
             if (!phaseValues.has(s)) {
@@ -392,7 +522,7 @@ export function checkPrimitiveReferences(capDir, protocolPath, contractPath = "s
                     for (const v of valuesToCheck) {
                         let resolved = false;
                         for (const pg of protocolGroups) {
-                            if (pg in lookup && lookup[pg].has(v)) {
+                            if (pg in lookup && lookup[pg].has(v)) { // cast: parsed schema/protocol IO data
                                 resolved = true;
                                 break;
                             }
@@ -409,4 +539,3 @@ export function checkPrimitiveReferences(capDir, protocolPath, contractPath = "s
     }
     return errors;
 }
-//# sourceMappingURL=capability.js.map

package/dist/validate/crossCapability.js

@@ -2,21 +2,22 @@ import fs from "node:fs";
 import path from "node:path";
 import { loadYamlMapping } from "../core/yaml.js";
 import { resolveSourceRoot } from "../core/sourceRoot.js";
-import { artifactSchemasDir as defaultArtifactSchemasDir, loadArtifactRegistry, } from "../registries/artifactRegistry.js";
+import { artifactSchemasDir as defaultArtifactSchemasDir, loadArtifactRegistry, registryModelPath as defaultRegistryModelPath, } from "../registries/artifactRegistry.js";
 function capabilitiesDirDefault() {
     return path.join(resolveSourceRoot(), "skills", "agentera", "capabilities");
 }
 function loadYaml(p) {
-    return loadYamlMapping(fs.readFileSync(p, "utf8"));
+    return loadYamlMapping(fs.readFileSync(p, "utf8")); // cast: YAML parse IO boundary
 }
-export function loadCanonicalArtifacts(artifactSchemasDir = defaultArtifactSchemasDir()) {
+export function loadCanonicalArtifacts(artifactSchemasDir = defaultArtifactSchemasDir(), registryModelPathArg = defaultRegistryModelPath()) {
     const out = new Map();
-    for (const [artifactId, record] of loadArtifactRegistry(artifactSchemasDir)) {
+    for (const [artifactId, record] of loadArtifactRegistry(artifactSchemasDir, registryModelPathArg)) {
         out.set(artifactId, {
             artifactId: record.artifactId,
             displayName: record.displayName,
             producers: record.producers,
             consumers: record.consumers,
+            implementationStatus: record.implementationStatus,
         });
     }
     return out;
@@ -47,7 +48,7 @@ export function loadCapabilityArtifacts(capabilitiesDir = capabilitiesDirDefault
                 continue;
             }
             const e = entry;
-            const artifactId = String(e.artifact_id ?? "").trim();
+            const artifactId = String(e.artifact ?? "").trim();
             const localRole = String(e.local_role ?? "").trim();
             if (!artifactId) {
                 continue;
@@ -102,9 +103,12 @@ function sortedListRepr(s) {
     const arr = [...s].sort();
     return "[" + arr.map((v) => `'${v}'`).join(", ") + "]";
 }
-export function validateGraph(artifactSchemasDir = defaultArtifactSchemasDir(), capabilitiesDir = capabilitiesDirDefault()) {
-    const registry = loadArtifactRegistry(artifactSchemasDir);
-    const canonical = loadCanonicalArtifacts(artifactSchemasDir);
+export function validateGraph(artifactSchemasDir = defaultArtifactSchemasDir(), capabilitiesDir = capabilitiesDirDefault(), registryModelPathArg = defaultRegistryModelPath()) {
+    // Thread the same model path into both registry loads so a synthetic
+    // test fixture (or a non-default install) resolves the same identity set in
+    // the canonical map and the dependency-graph walk below.
+    const registry = loadArtifactRegistry(artifactSchemasDir, registryModelPathArg);
+    const canonical = loadCanonicalArtifacts(artifactSchemasDir, registryModelPathArg);
     const capabilityArtifacts = loadCapabilityArtifacts(capabilitiesDir);
     const capabilityNames = new Set(listCapabilityDirs(capabilitiesDir));
     const errors = [];
@@ -116,7 +120,7 @@ export function validateGraph(artifactSchemasDir = defaultArtifactSchemasDir(),
         byArtifactId.get(record.artifactId).push(record);
         const name = displayName(record, registry);
         if (!canonical.has(record.artifactId)) {
-            errors.push(`${record.capability}: unknown artifact_id '${record.artifactId}'`);
+            errors.push(`${record.capability}: unknown artifact '${record.artifactId}'`);
             continue;
         }
         if (record.producers.size === 0 && record.consumers.size === 0) {
@@ -124,6 +128,8 @@ export function validateGraph(artifactSchemasDir = defaultArtifactSchemasDir(),
         }
     }
     for (const [artifactId, artifact] of canonical) {
+        if (artifact.implementationStatus === "declared_deferred")
+            continue;
         const records = byArtifactId.get(artifactId) ?? [];
         const producedBy = records.length ? unionSets(records.map((r) => r.producers)) : new Set();
         const consumedBy = records.length ? unionSets(records.map((r) => r.consumers)) : new Set();
@@ -142,4 +148,3 @@ export function validateGraph(artifactSchemasDir = defaultArtifactSchemasDir(),
     }
     return errors;
 }
-//# sourceMappingURL=crossCapability.js.map