@evalops/maestro 0.10.50 → 0.10.53

package/dist/agent/swarm/executor.js

@@ -11,7 +11,7 @@ import { unlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { formatDelegation } from "@evalops/contracts";
-import { codexSubagentTypeA2ASkillID } from "../../codex/subagent-dispatch-table.js";
+import { codexSubagentSkillToken, codexSubagentTypeA2ASkillID, } from "../../codex/subagent-dispatch-table.js";
 import { buildEvalOpsDelegationEnvironment, issueEvalOpsDelegationToken, } from "../../oauth/index.js";
 import { rankA2ACapabilityPeers } from "../../platform/a2a-capability-market.js";
 import { buildA2AUserMessage, cancelA2ATask, getA2ATask, normalizeA2ABaseUrl, resolveA2AServiceConfig, sendA2AMessage, } from "../../platform/a2a-client.js";
@@ -23,8 +23,13 @@ import { getEnvValue, trimString } from "../../platform/client.js";
 import { recordA2ADelegationTelemetry as recordA2ADelegationTelemetryEvent, recordSubagentDispatch, } from "../../telemetry.js";
 import { createLogger } from "../../utils/logger.js";
 import { sanitizeWithStaticMask } from "../../utils/secret-redactor.js";
+import { detectMissionSessionRole } from "../mission-artifacts.js";
 import { parseMode, resolveSubagentDispatch, } from "../modes.js";
+import { applySpecialistProfileToPrompt, resolveSpecialistProfile, } from "../specialist-profiles.js";
+import { parseSubagentType } from "../subagent-specs.js";
+import { evaluateSwarmCoverageGate } from "./coverage-gate.js";
 import { publishSwarmRuntimeEvent } from "./runtime-events.js";
+import { buildSwarmValidationDirective } from "./validation-directive.js";
 const logger = createLogger("agent:swarm:executor");
 /** Default timeout per task (5 minutes) */
 const DEFAULT_TASK_TIMEOUT_MS = 5 * 60 * 1000;
@@ -41,6 +46,7 @@ const A2A_SKILL_PRIMARY_TASK_CLASSES = new Map([
     ["maestro.subagent.code-writer", "code.implementation"],
     ["maestro.subagent.code-review", "code.review"],
     ["maestro.subagent.test-runner", "test.execution"],
+    ["maestro.subagent.browser-qa", "product.qa"],
     ["maestro.subagent.repo-explorer", "repo.inspect"],
     ["maestro.subagent.release-shepherd", "release.follow-through"],
 ]);
@@ -57,10 +63,18 @@ const SWARM_SUBAGENT_TASK_CLASSES = new Map([
     ["test", "test.execution"],
     ["ci", "test.execution"],
     ["ci-monitor", "test.execution"],
+    ["test-runner", "test.execution"],
+    ["browser-qa", "product.qa"],
+    ["browser", "product.qa"],
+    ["dogfood", "product.qa"],
+    ["product-qa", "product.qa"],
+    ["e2e-qa", "browser.e2e"],
+    ["ux-qa", "ux.repro"],
     ["planner", "agent.delegation"],
     ["minimal", "agent.delegation"],
     ["custom", "agent.delegation"],
 ]);
+const A2A_SUBAGENT_TASK_CLASS_OVERRIDES = new Set(["e2e-qa", "ux-qa"]);
 /** Teammate name prefixes for friendly identification */
 const TEAMMATE_NAMES = [
     "Alpha",
@@ -141,6 +155,13 @@ function cloneConfig(config) {
             }
             : undefined,
         tasks: config.tasks.map(cloneTask),
+        validationContract: config.validationContract
+            ? structuredClone(config.validationContract)
+            : undefined,
+        featureClaims: config.featureClaims?.map((claim) => ({
+            ...claim,
+            fulfills: [...claim.fulfills],
+        })),
     };
 }
 function cloneState(state) {
@@ -280,6 +301,9 @@ function buildDispatchEnv(dispatch, reasoningEffortOverride, runtimeSelection) {
     }
     return env;
 }
+function resolveMissionRoleForTeammate() {
+    return detectMissionSessionRole() === "validator" ? "validator" : "worker";
+}
 /**
  * SwarmExecutor manages a swarm of parallel agent instances.
  */
@@ -421,6 +445,30 @@ export class SwarmExecutor {
      * Execute the swarm - runs all tasks with available teammates.
      */
     async execute() {
+        // Pre-dispatch coverage gate: refuse to start when a validation contract
+        // is configured but its assertions are not fully covered by feature
+        // claims. No-ops when no contract is configured.
+        const coverage = evaluateSwarmCoverageGate({
+            validationContract: this.state.config.validationContract,
+            featureClaims: this.state.config.featureClaims,
+        });
+        if (!coverage.ok) {
+            const error = coverage.message ?? "Swarm coverage gate failed";
+            this.state.status = "failed";
+            this.state.error = error;
+            this.state.completedAt = Date.now();
+            this.emit({
+                type: "swarm_fail",
+                swarmId: this.state.id,
+                error,
+            });
+            this.emit({
+                type: "swarm_complete",
+                swarmId: this.state.id,
+                state: cloneState(this.state),
+            });
+            return cloneState(this.state);
+        }
         this.state.status = "running";
         this.emit({
             type: "swarm_start",
@@ -554,9 +602,11 @@ export class SwarmExecutor {
     async buildTeammateEnv(teammate, task, dispatch, runtimeSelection) {
         const baseEnv = {
             ...process.env,
+            MAESTRO_MISSION_WORKER: "1",
             MAESTRO_SWARM_MODE: "1",
             MAESTRO_SWARM_ID: this.state.id,
             MAESTRO_TEAMMATE_ID: teammate.id,
+            MAESTRO_MISSION_ROLE: resolveMissionRoleForTeammate(),
             ...buildDispatchEnv(dispatch, this.state.config.reasoningEffort, runtimeSelection),
         };
         try {
@@ -591,7 +641,11 @@ export class SwarmExecutor {
     }
     resolveTaskDispatch(task, teammate, options = {}) {
         const startedAt = Date.now();
-        const subagentType = task.subagentType ?? this.state.config.subagentType;
+        const requestedSubagentType = task.subagentType ?? this.state.config.subagentType;
+        if (!requestedSubagentType) {
+            return null;
+        }
+        const subagentType = parseSubagentType(requestedSubagentType);
         if (!subagentType) {
             return null;
         }
@@ -706,7 +760,7 @@ export class SwarmExecutor {
             config: peer.config,
             skillId,
             taskClass: this.resolveA2ATaskClass(task, options, skillId),
-            role: options.role ?? task.subagentType,
+            role: this.resolveA2ARole(task, options),
             tasksPath: options.tasksPath,
             peerEndpointHash: hashA2AEndpointUrlForTelemetry(peer.config.baseUrl),
             source: "registry",
@@ -769,7 +823,7 @@ export class SwarmExecutor {
             config,
             skillId: selectedSkillId,
             taskClass: this.resolveA2ATaskClass(task, options, selectedSkillId),
-            role: options.role ?? task.subagentType,
+            role: this.resolveA2ARole(task, options),
             tasksPath: options.tasksPath,
             peerAgentId: candidate.agent.id,
             peerEndpointHash: endpointHash,
@@ -829,20 +883,44 @@ export class SwarmExecutor {
         return peer?.entry.skills?.[0]?.id;
     }
     resolveA2ATaskClass(task, options, skillId) {
+        const explicitSkill = trimString(task.a2aSkillId) ?? trimString(options.skillId);
+        const requestedSubagentType = trimString(task.subagentType ?? this.state.config.subagentType);
+        const normalizedRequestedSubagentType = codexSubagentSkillToken(requestedSubagentType);
+        const parsedSubagentType = requestedSubagentType
+            ? parseSubagentType(requestedSubagentType)
+            : undefined;
+        const subagentType = parsedSubagentType ?? normalizedRequestedSubagentType;
+        const mappedSubagentTaskClass = normalizedRequestedSubagentType
+            ? (SWARM_SUBAGENT_TASK_CLASSES.get(normalizedRequestedSubagentType) ??
+                (parsedSubagentType
+                    ? SWARM_SUBAGENT_TASK_CLASSES.get(parsedSubagentType)
+                    : undefined))
+            : undefined;
+        if (mappedSubagentTaskClass &&
+            normalizedRequestedSubagentType &&
+            A2A_SUBAGENT_TASK_CLASS_OVERRIDES.has(normalizedRequestedSubagentType)) {
+            return mappedSubagentTaskClass;
+        }
         const mappedSkillTaskClass = skillId
             ? A2A_SKILL_PRIMARY_TASK_CLASSES.get(skillId)
             : undefined;
         if (mappedSkillTaskClass) {
             return mappedSkillTaskClass;
         }
-        if (skillId &&
-            (trimString(task.a2aSkillId) || trimString(options.skillId))) {
+        if (skillId && explicitSkill) {
             return undefined;
         }
-        const subagentType = trimString(task.subagentType ?? this.state.config.subagentType);
-        return ((subagentType
-            ? SWARM_SUBAGENT_TASK_CLASSES.get(subagentType)
-            : undefined) ?? subagentType);
+        return mappedSubagentTaskClass ?? subagentType ?? requestedSubagentType;
+    }
+    resolveA2ARole(task, options) {
+        const configuredRole = trimString(options.role);
+        if (configuredRole) {
+            return parseSubagentType(configuredRole) ?? configuredRole;
+        }
+        const requestedSubagentType = trimString(task.subagentType ?? this.state.config.subagentType);
+        return requestedSubagentType
+            ? (parseSubagentType(requestedSubagentType) ?? requestedSubagentType)
+            : undefined;
     }
     teammateIndex(teammate) {
         const index = this.state.teammates.findIndex((item) => item.id === teammate.id);
@@ -858,18 +936,64 @@ export class SwarmExecutor {
     }
     async spawnTeammate(teammate, task) {
         const tmpFile = join(tmpdir(), `${this.state.id}-${toSafeTaskTempBasename(task.id)}`);
+        const specialistProfile = task.specialistProfile
+            ? resolveSpecialistProfile(task.specialistProfile, this.state.config.cwd)
+            : null;
+        if (task.specialistProfile && !specialistProfile) {
+            throw new Error(`specialist profile not found or invalid: ${task.specialistProfile}`);
+        }
         const delegationPrompt = {
             goal: `Complete swarm task ${task.id} as teammate "${teammate.name}".`,
             context: `You are teammate "${teammate.name}" in swarm ${this.state.id}, working from plan file ${this.state.config.planFile}.`,
-            task: task.prompt,
+            task: applySpecialistProfileToPrompt(task.prompt, specialistProfile),
             evidence: task.files?.length
                 ? task.files.map((file) => `Relevant file: ${file}`)
                 : [],
-            validation: "Make the requested changes directly, add or update focused tests when behavior changes, and run the relevant verification before finishing.",
+            validation: buildSwarmValidationDirective(task.mocksAllowed),
             stoppingCondition: "Stop when the assigned task is complete and report what changed, what you verified, and any blockers. Do not broaden into unrelated tasks.",
         };
         const prompt = formatDelegation(delegationPrompt);
+        const requestedSubagentType = task.subagentType ?? this.state.config.subagentType;
         writeFileSync(tmpFile, prompt);
+        if (requestedSubagentType && !parseSubagentType(requestedSubagentType)) {
+            try {
+                unlinkSync(tmpFile);
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+            const error = `Invalid subagent type: ${requestedSubagentType}`;
+            this.state.activeTasks.delete(task.id);
+            this.state.failedTasks.add(task.id);
+            if (!this.state.config.continueOnFailure) {
+                this.state.status = "failed";
+            }
+            teammate.status = "failed";
+            teammate.error = error;
+            teammate.completedAt = Date.now();
+            teammate.currentTask = undefined;
+            this.emit({
+                type: "task_fail",
+                swarmId: this.state.id,
+                teammateId: teammate.id,
+                taskId: task.id,
+                error,
+            });
+            this.emit({
+                type: "teammate_complete",
+                swarmId: this.state.id,
+                teammate,
+            });
+            if (this.state.status === "running" &&
+                (this.state.pendingTasks.length > 0 ||
+                    this.state.activeTasks.size > 0) &&
+                this.state.config.continueOnFailure) {
+                teammate.status = "pending";
+                teammate.error = undefined;
+                teammate.completedAt = undefined;
+            }
+            return;
+        }
         const a2aConfig = this.resolveA2AConfig();
         if (a2aConfig) {
             void this.spawnA2ATeammate(teammate, task, prompt, tmpFile, a2aConfig);
@@ -1153,7 +1277,7 @@ export class SwarmExecutor {
                 route,
                 taskId: sent.task.id,
             });
-            await this.recordA2ASwarmTaskStart(route, task, sent.task, {
+            await this.recordA2ASwarmTaskStart(route, task, sent.task, prompt, {
                 messageId,
                 contextId,
             });
@@ -1273,6 +1397,7 @@ export class SwarmExecutor {
         });
     }
     buildA2ASwarmMessageMetadata(teammate, task, route) {
+        const missionRole = resolveMissionRoleForTeammate();
         const currentDelegationId = `${this.state.id}:${task.id}`;
         const contextId = `maestro-swarm:${this.state.id}:${task.id}`;
         const lineage = {
@@ -1292,6 +1417,8 @@ export class SwarmExecutor {
                 cwd: this.state.config.cwd,
                 taskId: task.id,
                 swarmId: this.state.id,
+                missionRole,
+                env: { MAESTRO_MISSION_ROLE: missionRole },
             }
             : undefined;
         const peerControl = {
@@ -1303,6 +1430,11 @@ export class SwarmExecutor {
             controlModes: ["followup", "steer", "interrupt", "cancel"],
             evidenceRequired: ["status", "artifact", "task", "workGraph"],
         };
+        const validationPolicy = {
+            schema: "evalops.maestro.swarm-validation-policy.v1",
+            mocksAllowed: task.mocksAllowed === true,
+            mode: task.mocksAllowed === true ? "mocks-allowed" : "real-integrations",
+        };
         return {
             requestKind: "maestro-swarm-task",
             transport: "a2a",
@@ -1311,6 +1443,8 @@ export class SwarmExecutor {
             teammateId: teammate.id,
             teammateName: teammate.name,
             taskId: task.id,
+            missionRole,
+            validation: validationPolicy,
             ...(route.skillId ? { a2aSkillId: route.skillId } : {}),
             ...(task.files?.length ? { files: task.files } : {}),
             swarm: lineage,
@@ -1319,8 +1453,10 @@ export class SwarmExecutor {
                 transport: "a2a",
                 peer: route.name,
                 peerControl,
+                validation: validationPolicy,
             },
             "evalops.peerControl": peerControl,
+            "evalops.validation": validationPolicy,
             ...(subagentRequest
                 ? { "evalops.subagentRequest": subagentRequest }
                 : {}),
@@ -1445,14 +1581,14 @@ export class SwarmExecutor {
             teammate.a2a = undefined;
         }
     }
-    async recordA2ASwarmTaskStart(route, task, remoteTask, ids) {
+    async recordA2ASwarmTaskStart(route, task, remoteTask, delegatedPrompt, ids) {
         try {
             await recordA2ATaskStart({
                 path: route.tasksPath,
                 peer: route.name,
                 peerDisplayName: route.displayName,
                 task: remoteTask,
-                text: task.prompt,
+                text: delegatedPrompt,
                 messageId: ids.messageId,
                 contextId: remoteTask.contextId ?? ids.contextId,
                 kind: "delegation",