@kontextmind/kxm 0.7.126 → 0.7.128

package/plugins/kxm/src/policy-draft.mjs

@@ -24,14 +24,17 @@ const MODEL_KEYS = Object.freeze([
   "thinking", "tags", "capabilities", "priority", "fallbacks", "limits",
 ]);
 const ROLE_KEYS = Object.freeze([
-  "schema", "id", "purpose", "permission", "description", "roster",
+  "schema", "id", "purpose", "permission", "description", "extends", "roster",
   "skills", "tools", "produces", "consumes", "policy",
 ]);
 const ORIGIN_KEYS = Object.freeze(["source", "sha256"]);
 const LIMIT_KEYS = Object.freeze(["contextTokens", "outputTokens", "timeoutMs"]);
 const TOOL_KEYS = Object.freeze(["preset", "allow", "deny"]);
 const TEMPLATE_KEYS = Object.freeze(["template", "schema"]);
-const POLICY_KEYS = Object.freeze(["vendorIndependenceRequired", "maxTransitions", "requiresGateVerification"]);
+const POLICY_KEYS = Object.freeze(["vendorIndependenceRequired", "maxTransitions", "requiresGateVerification", "fallback"]);
+const FALLBACK_KEYS = Object.freeze(["onError", "maxSwitches", "revert"]);
+const FALLBACK_ERRORS = Object.freeze(["rate_limit", "transport", "provider_unavailable"]);
+const FALLBACK_REVERT = Object.freeze(["next_run", "never"]);
 const ROSTER_ENTRY_KEYS = Object.freeze(["route", "effort", "mode"]);
 const CRITIC_PURPOSES = Object.freeze(["reviewer-arch", "reviewer-cli"]);
 
@@ -318,6 +321,9 @@ function validateRoleShape(document, id, label, issues) {
   if (document.id !== undefined && document.id !== id) {
     issues.push(issue("schema", "identity_mismatch", label, `declared id ${String(document.id)} does not match ${id}`));
   }
+  if (document.extends !== undefined && !identifier(document.extends)) {
+    issues.push(issue("schema", "schema_pattern", label, "extends must be a role identifier"));
+  }
   if (document.purpose !== undefined && !POLICY_DRAFT_PURPOSES.includes(document.purpose)) {
     issues.push(issue("schema", "unsupported_purpose", label, "purpose must be a runner role label"));
   }
@@ -382,6 +388,23 @@ function validateRoleShape(document, id, label, issues) {
     if (document.policy.maxTransitions !== undefined && (!Number.isInteger(document.policy.maxTransitions) || document.policy.maxTransitions < 1)) {
       issues.push(issue("schema", "schema_type", `${label}.policy`, "maxTransitions must be a positive integer"));
     }
+    if (document.policy.fallback !== undefined) {
+      const fallback = document.policy.fallback;
+      const path = `${label}.policy.fallback`;
+      if (!closedObject(fallback, FALLBACK_KEYS, path, issues)) return;
+      if (fallback.onError !== undefined) {
+        if (!Array.isArray(fallback.onError) || new Set(fallback.onError).size !== fallback.onError.length
+          || fallback.onError.some((item) => !FALLBACK_ERRORS.includes(item))) {
+          issues.push(issue("schema", "schema_enum", path, "onError must be unique rate_limit, transport, or provider_unavailable values"));
+        }
+      }
+      if (fallback.maxSwitches !== undefined && (!Number.isInteger(fallback.maxSwitches) || fallback.maxSwitches < 0)) {
+        issues.push(issue("schema", "schema_type", path, "maxSwitches must be an integer >= 0"));
+      }
+      if (fallback.revert !== undefined && !FALLBACK_REVERT.includes(fallback.revert)) {
+        issues.push(issue("schema", "schema_enum", path, "revert must be next_run or never"));
+      }
+    }
   }
 }
 
@@ -431,20 +454,15 @@ function validateModelSemantics(model, label, options, evidence, issues) {
         issues.push(issue("semantic", "pi_native_vendor_forbidden", label, "native vendor cannot use Pi"));
       }
     }
-    const origin = model.origin;
-    if (isObject(origin) && typeof origin.source === "string" && typeof origin.sha256 === "string") {
-      if (!own(evidence, origin.source)) {
-        issues.push(issue("semantic", "origin_evidence_missing", label, `missing evidence bytes for ${origin.source}`));
-      } else if (sha256Bytes(evidence[origin.source]) !== origin.sha256) {
-        issues.push(issue("semantic", "origin_hash_mismatch", label, "origin evidence hash does not match supplied bytes"));
-      }
-    }
-  } else {
-    if (vendor !== ceiling.provider || (typeof model.model === "string" && model.model.includes("/"))) {
-      issues.push(issue("semantic", "native_vendor_mismatch", label, "native route vendor or model does not match the harness ceiling"));
-    }
-    if (own(model, "origin")) {
-      issues.push(issue("semantic", "origin_unexpected", label, "origin is only valid for Pi routes"));
+  } else if (vendor !== ceiling.provider || (typeof model.model === "string" && model.model.includes("/"))) {
+    issues.push(issue("semantic", "native_vendor_mismatch", label, "native route vendor or model does not match the harness ceiling"));
+  }
+  const origin = model.origin;
+  if (isObject(origin) && typeof origin.source === "string" && typeof origin.sha256 === "string") {
+    if (!own(evidence, origin.source)) {
+      issues.push(issue("semantic", "origin_evidence_missing", label, `missing evidence bytes for ${origin.source}`));
+    } else if (sha256Bytes(evidence[origin.source]) !== origin.sha256) {
+      issues.push(issue("semantic", "origin_hash_mismatch", label, "origin evidence hash does not match supplied bytes"));
     }
   }
 }
@@ -501,6 +519,27 @@ function validateRoleSemantics(role, id, label, models, options, issues) {
   }
 }
 
+function validateExtends(roles, issues) {
+  for (const [id, role] of roles) {
+    if (role.extends === undefined) continue;
+    const label = `roles/${id}`;
+    if (!roles.has(role.extends)) {
+      issues.push(issue("reference", "role_extends_unknown", label, `extends names unknown role ${role.extends}`));
+      continue;
+    }
+    const seen = new Set([id]);
+    let current = role.extends;
+    while (typeof current === "string" && current.length > 0) {
+      if (seen.has(current)) {
+        issues.push(issue("semantic", "role_extends_cycle", label, `extends cycle: ${[...seen, current].join(" -> ")}`));
+        break;
+      }
+      seen.add(current);
+      current = roles.get(current)?.extends;
+    }
+  }
+}
+
 function validateCriticVendors(roles, models, options, issues) {
   const aliases = options.vendorAliases ?? {};
   const critics = [];
@@ -569,6 +608,7 @@ export function validatePolicyDraft(input, options) {
     normalized.id = entry.id;
     roles.set(entry.id, normalized);
   }
+  validateExtends(roles, issues);
   validateCriticVendors(roles, models, options, issues);
   if (issues.length > 0) return { ok: false, issues: sortIssues(issues) };
 

package/plugins/kxm/src/project-config.ts

@@ -9,6 +9,8 @@ import {
   parseRestrictedYaml as parseRestrictedYamlShared,
   type KxmYamlLimits,
 } from "./restricted-yaml.mjs";
+import { pathToFileURL } from "node:url";
+import { validatePolicyDraft } from "./policy-draft.mjs";
 import { resolveKxmTemplateBaseline } from "./template.ts";
 import { findKxmRepoRoot } from "./repo-root.ts";
 import { BUILTIN_HARNESS_IDS, DEFAULT_HARNESS, validateHarnessModelPair } from "./harness.ts";
@@ -38,7 +40,7 @@ export class KxmConfigError extends Error {
   }
 }
 
-export type KxmResourceKind = "project" | "repository" | "agent" | "model" | "environment" | "workflow" | "gate-registry";
+export type KxmResourceKind = "project" | "repository" | "agent" | "model" | "role" | "environment" | "workflow" | "gate-registry";
 
 export interface KxmResource {
   kind: KxmResourceKind;
@@ -54,6 +56,7 @@ export interface KxmProjectBundle {
   repositories: ReadonlyMap<string, KxmResource>;
   agents: ReadonlyMap<string, KxmResource>;
   models: ReadonlyMap<string, KxmResource>;
+  roles: ReadonlyMap<string, KxmResource>;
   workflows: ReadonlyMap<string, KxmResource>;
   environments: readonly KxmResource[];
   gateRegistry?: KxmResource;
@@ -91,7 +94,8 @@ const RESOURCE_SCHEMA: Readonly<Record<KxmResourceKind, { identity: string; file
   project: { identity: "kxm.project.v1", file: "project.schema.json" },
   repository: { identity: "kxm.repository.v1", file: "repository.schema.json" },
   agent: { identity: "kxm.agent.v1", file: "agent.schema.json" },
-  model: { identity: "kxm.model.v1", file: "model.schema.json" },
+  model: { identity: "kxm.model.v2", file: "model.schema.json" },
+  role: { identity: "kxm.role.v2", file: "role.schema.json" },
   environment: { identity: "kxm.environment.v1", file: "environment.schema.json" },
   workflow: { identity: "kxm.workflow.v1", file: "workflow.schema.json" },
   "gate-registry": { identity: "kxm.gate-registry.v1", file: "gate-registry.schema.json" },
@@ -516,7 +520,7 @@ function listNamedResources(
   root: string,
   directory: string,
   logicalDirectory: string,
-  kind: "agent" | "model" | "workflow",
+  kind: "agent" | "model" | "role" | "workflow",
   replacedId?: string,
 ): Map<string, KxmResource> {
   const resources = new Map<string, KxmResource>();
@@ -658,7 +662,7 @@ function modelCandidates(selectorValue: JsonValue | undefined, models: ReadonlyM
     return [{
       key: `profile:${profile}`,
       profile,
-      ...(stringValue(resource.value.provider) ? { provider: stringValue(resource.value.provider)! } : {}),
+      ...(stringValue(resource.value.provider) || stringValue(resource.value.vendor) ? { provider: (stringValue(resource.value.provider) ?? stringValue(resource.value.vendor))! } : {}),
       ...(stringValue(resource.value.model) ? { model: stringValue(resource.value.model)! } : {}),
     }];
   }
@@ -671,7 +675,7 @@ function modelCandidates(selectorValue: JsonValue | undefined, models: ReadonlyM
       .map((resource) => ({
         key: `profile:${resource.id ?? "unknown"}`,
         ...(resource.id ? { profile: resource.id } : {}),
-        ...(stringValue(resource.value.provider) ? { provider: stringValue(resource.value.provider)! } : {}),
+        ...(stringValue(resource.value.provider) || stringValue(resource.value.vendor) ? { provider: (stringValue(resource.value.provider) ?? stringValue(resource.value.vendor))! } : {}),
         ...(stringValue(resource.value.model) ? { model: stringValue(resource.value.model)! } : {}),
       }));
   }
@@ -1208,10 +1212,26 @@ function validateBundle(
         const rosterEntries = valuesOf(roleObj ?? {}, "roster")
           .map((candidate) => objectValue(candidate))
           .filter((entry): entry is JsonObject => Boolean(entry));
-        const enabledRosterModels = rosterEntries
-          .filter((entry) => entry.enabled !== false)
-          .map((entry) => stringValue(entry.model))
-          .filter((m): m is string => Boolean(m));
+        const enabledRosterModels = rosterEntries.flatMap((entry) => {
+          const direct = stringValue(entry.model);
+          const route = stringValue(entry.route);
+          const named: string[] = direct ? [direct] : [];
+          if (route) {
+            const modelFile = join(projectRoot, ".kxm", "models", `${route}.yaml`);
+            if (existsSync(modelFile)) {
+              try {
+                const modelDoc = objectValue(parseRestrictedYaml(readFileSync(modelFile, "utf8"), modelFile));
+                const model = modelDoc ? stringValue(modelDoc.model) : undefined;
+                const vendor = modelDoc ? stringValue(modelDoc.vendor) : undefined;
+                const harness = modelDoc ? stringValue(modelDoc.harness) : undefined;
+                if (model) named.push(model);
+                if (vendor && model) named.push(`${vendor}/${model}`);
+                if (harness && model) named.push(`${harness}/${model}`);
+              } catch { /* schema issues are reported by resource validation */ }
+            }
+          }
+          return named;
+        });
 
         const agentModelObj = objectValue(implementerAgent.value.model);
         const agentModelStr = stringValue(implementerAgent.value.model);
@@ -1233,9 +1253,94 @@ function validateBundle(
     }
   }
 
+  if (projectRoot && existsSync(join(projectRoot, ".kxm", "roster.yaml"))) {
+    issues.push(...developerRolePolicyIssues(projectRoot));
+  }
+
   return sortIssues(issues);
 }
 
+function developerCeilings(): {
+  ok: true;
+  ROUTES: Record<string, { provider: string; permissions: readonly string[]; models?: readonly string[]; roles?: readonly string[]; efforts?: readonly string[] }>;
+  NATIVE_PI_BRAKE_PROVIDERS: string[];
+  PI_ALLOWED_PROVIDERS: string[];
+  PI_NATIVE_VENDOR_PROVIDERS: Record<string, string>;
+} | { ok: false; detail: string } {
+  const script = join(findKxmRepoRoot(import.meta.url), "scripts", "harness-run.mjs");
+  let loaded;
+  try {
+    loaded = spawnSync(process.execPath, ["--input-type=module", "-e", `const m = await import(${JSON.stringify(pathToFileURL(script).href)}); process.stdout.write(JSON.stringify({ROUTES:m.ROUTES,NATIVE_PI_BRAKE_PROVIDERS:m.NATIVE_PI_BRAKE_PROVIDERS,PI_ALLOWED_PROVIDERS:m.PI_ALLOWED_PROVIDERS,PI_NATIVE_VENDOR_PROVIDERS:m.PI_NATIVE_VENDOR_PROVIDERS}))`], {
+      encoding: "utf8",
+      timeout: 15000,
+    });
+  } catch (error) {
+    return { ok: false, detail: error instanceof Error ? error.message : String(error) };
+  }
+  if (loaded.error) {
+    const code = (loaded.error as NodeJS.ErrnoException).code;
+    const detail = code === "ETIMEDOUT" || loaded.signal ? `timed out after 15s (${loaded.error.message})` : loaded.error.message;
+    return { ok: false, detail };
+  }
+  if (loaded.status !== 0 || !loaded.stdout) {
+    const stderr = (loaded.stderr ?? "").trim();
+    return { ok: false, detail: stderr || `scripts/harness-run.mjs exited ${loaded.status}` };
+  }
+  try {
+    return { ok: true, ...JSON.parse(loaded.stdout) as { ROUTES: Record<string, { provider: string; permissions: readonly string[]; models?: readonly string[]; roles?: readonly string[]; efforts?: readonly string[] }>; NATIVE_PI_BRAKE_PROVIDERS: string[]; PI_ALLOWED_PROVIDERS: string[]; PI_NATIVE_VENDOR_PROVIDERS: Record<string, string> } };
+  } catch (error) {
+    return { ok: false, detail: `ceilings JSON parse failed: ${error instanceof Error ? error.message : String(error)}` };
+  }
+}
+
+function developerRolePolicyIssues(projectRoot: string): KxmConfigIssue[] {
+  const rolesDir = join(projectRoot, ".kxm", "roles");
+  const modelsDir = join(projectRoot, ".kxm", "models");
+  const roles: Record<string, JsonObject> = {};
+  const models: Record<string, JsonObject> = {};
+  const evidence: Record<string, string> = {};
+  const parseIssues: KxmConfigIssue[] = [];
+  const readMap = (dir: string, into: Record<string, JsonObject>, skipInventory: boolean) => {
+    if (!existsSync(dir)) return;
+    for (const name of readdirSync(dir)) {
+      if (!name.endsWith(".yaml")) continue;
+      const id = basename(name, ".yaml");
+      if (skipInventory && id === "inventory") continue;
+      try {
+        const value = parseRestrictedYaml(readFileSync(join(dir, name), "utf8"), `${dir}/${name}`);
+        into[id] = value;
+      } catch (error) {
+        if (error instanceof KxmConfigError) {
+          parseIssues.push(...error.issues);
+          continue;
+        }
+      }
+    }
+  };
+  readMap(rolesDir, roles, false);
+  readMap(modelsDir, models, true);
+  for (const model of Object.values(models)) {
+    const origin = objectValue(model.origin);
+    const source = origin ? stringValue(origin.source) : undefined;
+    if (!source || evidence[source] !== undefined) continue;
+    const evidenceFile = isAbsolute(source) ? source : join(projectRoot, source);
+    if (existsSync(evidenceFile)) evidence[source] = readFileSync(evidenceFile, "utf8");
+  }
+  const ceilings = developerCeilings();
+  if (!ceilings.ok) {
+    return [...parseIssues, issue("semantic", "developer_ceilings_unavailable", ".kxm/roster.yaml", `developer ceilings could not be loaded: ${ceilings.detail}`)];
+  }
+  const result = validatePolicyDraft({ models, roles, evidence }, {
+    ceilings: ceilings.ROUTES,
+    nativePiBrakeProviders: ceilings.NATIVE_PI_BRAKE_PROVIDERS,
+    piAllowedProviders: ceilings.PI_ALLOWED_PROVIDERS,
+    piNativeVendorProviders: ceilings.PI_NATIVE_VENDOR_PROVIDERS,
+    vendorAliases: { "x-ai": "xai", moonshotai: "moonshot", "google-ai": "google", qwen: "alibaba" },
+  });
+  if (result.ok) return parseIssues;
+  return [...parseIssues, ...result.issues.map((entry) => issue(entry.phase, entry.code, entry.file, entry.message))];
+}
+
 export function kxmCanonicalJson(value: JsonValue): string {
   if (value === null || typeof value !== "object") return JSON.stringify(value);
   if (Array.isArray(value)) return `[${value.map((candidate) => kxmCanonicalJson(candidate)).join(",")}]`;
@@ -1385,6 +1490,11 @@ function loadProjectBundle(
 
   const agents = listNamedResources(registry, root, join(root, ".kxm", "agents"), ".kxm/agents", "agent");
   const models = listNamedResources(registry, root, join(root, ".kxm", "models"), ".kxm/models", "model");
+  const roles = listNamedResources(registry, root, join(root, ".kxm", "roles"), ".kxm/roles", "role", writerRole === undefined ? undefined : "writer");
+  if (writerRole !== undefined) {
+    const logicalPath = ".kxm/roles/writer.yaml";
+    roles.set("writer", { kind: "role", id: "writer", file: join(root, logicalPath), logicalPath, value: resourceValue(registry, writerRole, logicalPath, "role") });
+  }
   const workflows = listNamedResources(registry, root, join(root, ".kxm", "workflows"), ".kxm/workflows", "workflow", workflowCandidate?.id);
   if (workflowCandidate) {
     const { id, document } = workflowCandidate;
@@ -1514,7 +1624,7 @@ function loadProjectBundle(
 
   const issues = validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, root, writerRole);
   if (issues.length > 0) throw new KxmConfigError(issues);
-  const resources = [project, ...repositories.values(), ...agents.values(), ...models.values(), ...workflows.values(), ...environments, ...(gateRegistry ? [gateRegistry] : [])]
+  const resources = [project, ...repositories.values(), ...agents.values(), ...models.values(), ...roles.values(), ...workflows.values(), ...environments, ...(gateRegistry ? [gateRegistry] : [])]
     .sort((left, right) => compareCodeUnits(left.logicalPath, right.logicalPath));
   return {
     projectRoot: root,
@@ -1522,6 +1632,7 @@ function loadProjectBundle(
     repositories,
     agents,
     models,
+    roles,
     workflows,
     environments,
     ...(gateRegistry ? { gateRegistry } : {}),

package/plugins/kxm/src/repair.ts

@@ -48,6 +48,7 @@ function resourceKindForTemplatePath(path: string): KxmResourceKind {
   if (path.endsWith("repo.yaml")) return "repository";
   if (path.startsWith(".kxm/agents/")) return "agent";
   if (path.startsWith(".kxm/models/")) return "model";
+  if (path.startsWith(".kxm/roles/")) return "role";
   if (path.startsWith(".kxm/workflows/")) return "workflow";
   return "environment";
 }