@mxf-dev/core 2.0.5 → 3.0.0

package/dist/services/TaskEffectivenessService.js

@@ -27,14 +27,12 @@ import { v4 as uuidv4 } from 'uuid';
 import { Logger } from '../utils/Logger.js';
 import { EventBus } from '../events/EventBus.js';
 import { Events } from '../events/EventNames.js';
-import { AgentPerformanceService } from './AgentPerformanceService.js';
 import { TaskEffectivenessModel } from '../models/taskEffectiveness.js';
 /**
  * Service for tracking and analyzing task effectiveness
  */
 export class TaskEffectivenessService {
     logger;
-    performanceService;
     static instance;
     // Active task tracking
     activeTasks = new Map();
@@ -59,7 +57,6 @@ export class TaskEffectivenessService {
     };
     constructor() {
         this.logger = new Logger('info', 'TaskEffectivenessService', 'server');
-        this.performanceService = AgentPerformanceService.getInstance();
         this.setupEventListeners();
     }
     static getInstance() {
@@ -68,15 +65,35 @@ export class TaskEffectivenessService {
         }
         return TaskEffectivenessService.instance;
     }
+    getTaskKey(taskId, agentId, channelId) {
+        return JSON.stringify([agentId, channelId, taskId]);
+    }
+    requireTenantIdentity(agentId, channelId) {
+        if (!agentId?.trim() || !channelId?.trim() ||
+            agentId !== agentId.trim() || channelId !== channelId.trim()) {
+            throw new Error('Agent ID and channel ID are required');
+        }
+    }
+    requireTaskIdentity(taskId) {
+        if (!taskId?.trim() || taskId !== taskId.trim()) {
+            throw new Error('A canonical task ID is required');
+        }
+    }
     /**
      * Start tracking a new task
      */
     startTask(definition) {
         try {
-            if (!definition.channelId || !definition.taskType || !definition.description) {
+            if (!definition.agentId || !definition.channelId || !definition.taskType || !definition.description) {
                 throw new Error('Missing required task definition fields');
             }
+            this.requireTenantIdentity(definition.agentId, definition.channelId);
             const taskId = definition.taskId || uuidv4();
+            this.requireTaskIdentity(taskId);
+            const taskKey = this.getTaskKey(taskId, definition.agentId, definition.channelId);
+            if (this.activeTasks.has(taskKey)) {
+                throw new Error(`Task ${taskId} is already being tracked for this agent and channel`);
+            }
             const metrics = {
                 taskId,
                 metadata: {
@@ -91,7 +108,7 @@ export class TaskEffectivenessService {
                     uniqueTools: [],
                     agentInteractions: 0,
                     humanInterventions: 0,
-                    autonomyScore: 1.0 // Starts at 100%, decreases with interventions
+                    autonomyScore: 1.0
                 },
                 quality: {
                     goalAchieved: false,
@@ -106,26 +123,28 @@ export class TaskEffectivenessService {
                     memoryOperations: 0
                 },
                 collaboration: {
-                    participatingAgents: [],
+                    participatingAgents: [definition.agentId],
                     messageCount: 0,
                     coordinationCount: 0,
                     knowledgeTransfers: 0,
                     collaborationScore: 0
                 }
             };
-            this.activeTasks.set(taskId, metrics);
-            this.taskDefinitions.set(taskId, definition);
-            this.taskEvents.set(taskId, []);
-            // Emit task started event
+            this.activeTasks.set(taskKey, metrics);
+            this.taskDefinitions.set(taskKey, definition);
+            this.taskEvents.set(taskKey, []);
             this.recordEvent({
                 eventId: uuidv4(),
                 taskId,
+                agentId: definition.agentId,
+                channelId: definition.channelId,
                 timestamp: Date.now(),
                 type: 'start',
                 details: { definition }
             });
-            EventBus.server.emit(Events.Analytics.TASK_STARTED, createBaseEventPayload(Events.Analytics.TASK_STARTED, 'system', definition.channelId, {
+            EventBus.server.emit(Events.Analytics.TASK_STARTED, createBaseEventPayload(Events.Analytics.TASK_STARTED, definition.agentId, definition.channelId, {
                 taskId,
+                agentId: definition.agentId,
                 channelId: definition.channelId,
                 taskType: definition.taskType,
                 timestamp: new Date()
@@ -141,60 +160,57 @@ export class TaskEffectivenessService {
      * Record a task execution event
      */
     recordEvent(event) {
-        try {
-            if (!event.taskId || !event.type) {
-                this.logger.warn('Invalid event: missing taskId or type');
-                return;
-            }
-            const events = this.taskEvents.get(event.taskId);
-            if (events) {
-                events.push(event);
-            }
-            // Update metrics based on event
-            const metrics = this.activeTasks.get(event.taskId);
-            if (metrics) {
-                this.updateMetricsFromEvent(metrics, event);
-            }
-            else {
-            }
-            // Emit event for analytics tracking
-            EventBus.server.emit(Events.Analytics.TASK_EFFECTIVENESS_EVENT, createBaseEventPayload(Events.Analytics.TASK_EFFECTIVENESS_EVENT, event.agentId || 'unknown', 'global', {
-                taskId: event.taskId,
-                agentId: event.agentId || 'unknown',
-                eventType: event.type,
-                details: event.details,
-                timestamp: new Date()
-            }));
-        }
-        catch (error) {
-            this.logger.error(`Failed to record event: ${error}`);
-        }
+        if (!event.taskId || !event.type) {
+            throw new Error('Task ID and event type are required');
+        }
+        this.requireTaskIdentity(event.taskId);
+        this.requireTenantIdentity(event.agentId, event.channelId);
+        const taskKey = this.getTaskKey(event.taskId, event.agentId, event.channelId);
+        const events = this.taskEvents.get(taskKey);
+        const metrics = this.activeTasks.get(taskKey);
+        if (!events || !metrics) {
+            throw new Error(`Active task ${event.taskId} was not found for this agent and channel`);
+        }
+        events.push(event);
+        this.updateMetricsFromEvent(metrics, event);
+        EventBus.server.emit(Events.Analytics.TASK_EFFECTIVENESS_EVENT, createBaseEventPayload(Events.Analytics.TASK_EFFECTIVENESS_EVENT, event.agentId, event.channelId, {
+            taskId: event.taskId,
+            agentId: event.agentId,
+            channelId: event.channelId,
+            eventType: event.type,
+            details: event.details,
+            timestamp: new Date()
+        }));
     }
     /**
      * Update task quality metrics
      */
-    updateQuality(taskId, updates, agentId) {
-        // Quality is recorded while a task is running. A completed task's metrics
-        // are already persisted and are not amended here.
-        const metrics = this.activeTasks.get(taskId);
-        if (metrics) {
-            metrics.quality = { ...metrics.quality, ...updates };
-            // Emit quality update event
-            EventBus.server.emit(Events.Analytics.TASK_EFFECTIVENESS_QUALITY_UPDATE, createBaseEventPayload(Events.Analytics.TASK_EFFECTIVENESS_QUALITY_UPDATE, agentId || 'unknown', 'global', {
-                taskId,
-                agentId: agentId || 'unknown',
-                qualityUpdates: updates,
-                timestamp: new Date()
-            }));
+    updateQuality(taskId, agentId, channelId, updates) {
+        this.requireTenantIdentity(agentId, channelId);
+        this.requireTaskIdentity(taskId);
+        const taskKey = this.getTaskKey(taskId, agentId, channelId);
+        const metrics = this.activeTasks.get(taskKey);
+        if (!metrics) {
+            throw new Error(`Active task ${taskId} was not found for this agent and channel`);
         }
+        metrics.quality = { ...metrics.quality, ...updates };
+        EventBus.server.emit(Events.Analytics.TASK_EFFECTIVENESS_QUALITY_UPDATE, createBaseEventPayload(Events.Analytics.TASK_EFFECTIVENESS_QUALITY_UPDATE, agentId, channelId, {
+            taskId,
+            agentId,
+            channelId,
+            qualityUpdates: updates,
+            timestamp: new Date()
+        }));
     }
     /**
      * Complete a task and calculate final metrics
      */
-    async completeTask(taskId, success, customMetrics) {
-        const metrics = this.activeTasks.get(taskId);
+    async completeTask(taskId, agentId, channelId, success, customMetrics) {
+        this.requireTenantIdentity(agentId, channelId);
+        this.requireTaskIdentity(taskId);
+        const taskKey = this.getTaskKey(taskId, agentId, channelId);
+        const metrics = this.activeTasks.get(taskKey);
         if (!metrics) {
-            this.logger.warn(`Cannot complete unknown task ${taskId}`);
             return null;
         }
         // Update final metrics
@@ -211,11 +227,13 @@ export class TaskEffectivenessService {
         }
         // Persist to MongoDB, then drop from the active set. Persist first: if
         // it throws, the task stays active rather than disappearing entirely.
-        await this.persistTaskToDB(taskId, metrics);
-        this.activeTasks.delete(taskId);
+        await this.persistTaskToDB(taskId, agentId, channelId, metrics);
+        this.activeTasks.delete(taskKey);
         // Emit completion event
-        EventBus.server.emit(Events.Analytics.TASK_COMPLETED, createBaseEventPayload(Events.Analytics.TASK_COMPLETED, 'system', 'global', {
+        EventBus.server.emit(Events.Analytics.TASK_COMPLETED, createBaseEventPayload(Events.Analytics.TASK_COMPLETED, agentId, channelId, {
             taskId,
+            agentId,
+            channelId,
             metrics,
             success,
             timestamp: new Date()
@@ -230,11 +248,14 @@ export class TaskEffectivenessService {
      *
      * @returns null when the task or its definition is unknown
      */
-    async compareWithBaseline(taskId) {
-        let metrics = this.activeTasks.get(taskId);
-        let definition = this.taskDefinitions.get(taskId);
+    async compareWithBaseline(taskId, agentId, channelId) {
+        this.requireTenantIdentity(agentId, channelId);
+        this.requireTaskIdentity(taskId);
+        const taskKey = this.getTaskKey(taskId, agentId, channelId);
+        let metrics = this.activeTasks.get(taskKey);
+        let definition = this.taskDefinitions.get(taskKey);
         if (!metrics || !definition) {
-            const taskDoc = await TaskEffectivenessModel.findOne({ taskId }).exec();
+            const taskDoc = await TaskEffectivenessModel.findOne({ taskId, agentId, channelId }).exec();
             if (taskDoc) {
                 metrics = metrics ?? taskDoc.metrics;
                 definition = definition ?? taskDoc.definition;
@@ -278,25 +299,28 @@ export class TaskEffectivenessService {
         // Generate insights
         comparison.summary.achievements = this.identifyAchievements(metrics, baseline);
         comparison.summary.improvements = this.identifyImprovements(metrics);
-        comparison.summary.recommendations = this.generateRecommendations(metrics);
+        comparison.summary.recommendations = this.generateRecommendations(metrics, taskKey);
         return comparison;
     }
-    /**
-     * Effectiveness analytics for a time period, computed from persisted tasks.
-     *
-     * Reads from MongoDB, so results cover every task ever completed — not just
-     * the ones this process happened to run.
-     *
-     * @param startTime Start of the window (epoch ms)
-     * @param endTime End of the window (epoch ms)
-     * @param channelId Optional channel filter
-     * @param taskType Optional task-type filter
-     * @throws If the query fails. Effectiveness numbers computed from an empty
-     *         result set would look like real "no activity" data.
-     */
-    async getAnalytics(startTime, endTime, channelId, taskType) {
+    /** Effectiveness analytics for one exact agent and channel. */
+    async getAnalytics(startTime, endTime, agentId, channelId, taskType) {
+        this.requireTenantIdentity(agentId, channelId);
+        const tasks = await this.findCompletedTasks({
+            startTime,
+            endTime,
+            agentId,
+            channelId,
+            taskType
+        });
+        return this.computeAnalyticsFromRecords(tasks, startTime, endTime);
+    }
+    /** Channel-wide analytics intended only for the admin-authenticated REST surface. */
+    async getAdministrativeChannelAnalytics(startTime, endTime, channelId, taskType) {
+        if (!channelId?.trim()) {
+            throw new Error('Channel ID is required');
+        }
         const tasks = await this.findCompletedTasks({ startTime, endTime, channelId, taskType });
-        return this.computeAnalyticsFromMetrics(tasks, startTime, endTime);
+        return this.computeAnalyticsFromRecords(tasks, startTime, endTime);
     }
     /**
      * Query persisted task effectiveness records.
@@ -307,6 +331,9 @@ export class TaskEffectivenessService {
         const query = {
             'metrics.metadata.startTime': { $gte: filter.startTime, $lte: filter.endTime }
         };
+        if (!Number.isFinite(filter.startTime) || !Number.isFinite(filter.endTime) || filter.startTime > filter.endTime) {
+            throw new Error('A valid effectiveness analytics time range is required');
+        }
         if (filter.channelId) {
             query.channelId = filter.channelId;
         }
@@ -314,11 +341,20 @@ export class TaskEffectivenessService {
             query['metrics.metadata.type'] = filter.taskType;
         }
         if (filter.agentId) {
-            query.agentIds = filter.agentId;
+            query.agentId = filter.agentId;
         }
         try {
             const docs = await TaskEffectivenessModel.find(query).exec();
-            return docs.map(doc => doc.metrics);
+            return docs.map(doc => {
+                if (!doc.agentId || !doc.channelId) {
+                    throw new Error(`Task effectiveness record ${doc.taskId} has no tenant identity`);
+                }
+                return {
+                    agentId: doc.agentId,
+                    channelId: doc.channelId,
+                    metrics: doc.metrics
+                };
+            });
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -333,21 +369,24 @@ export class TaskEffectivenessService {
      *         that is not written down is history that is simply gone; the caller
      *         needs to know.
      */
-    async persistTaskToDB(taskId, metrics) {
-        const definition = this.taskDefinitions.get(taskId);
+    async persistTaskToDB(taskId, agentId, channelId, metrics) {
+        const taskKey = this.getTaskKey(taskId, agentId, channelId);
+        const definition = this.taskDefinitions.get(taskKey);
         if (!definition) {
             throw new Error(`Cannot persist task ${taskId}: no task definition was registered for it`);
         }
         try {
-            await TaskEffectivenessModel.findOneAndUpdate({ taskId }, {
+            await TaskEffectivenessModel.findOneAndUpdate({ taskId, agentId, channelId }, {
                 $set: {
-                    channelId: definition.channelId,
+                    agentId,
+                    channelId,
                     agentIds: metrics.collaboration.participatingAgents,
                     definition,
                     metrics,
+                    completedAt: new Date(),
                     updatedAt: new Date()
                 }
-            }, { upsert: true, new: true }).exec();
+            }, { upsert: true, new: true, runValidators: true, setDefaultsOnInsert: true }).exec();
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -358,7 +397,7 @@ export class TaskEffectivenessService {
     /**
      * Compute analytics from metrics array
      */
-    computeAnalyticsFromMetrics(tasks, startTime, endTime) {
+    computeAnalyticsFromRecords(records, startTime, endTime) {
         // Initialize analytics (similar to existing getAnalytics method)
         const analytics = {
             period: { start: startTime, end: endTime },
@@ -375,8 +414,7 @@ export class TaskEffectivenessService {
                 effectiveTeams: []
             }
         };
-        // Aggregate by task type (reuse existing logic)
-        for (const task of tasks) {
+        for (const { metrics: task } of records) {
             const type = task.metadata.type;
             if (!analytics.byTaskType[type]) {
                 analytics.byTaskType[type] = {
@@ -404,10 +442,53 @@ export class TaskEffectivenessService {
         }
         // Calculate success rates
         for (const [type, stats] of Object.entries(analytics.byTaskType)) {
-            const typeTasks = tasks.filter(t => t.metadata.type === type);
+            const typeTasks = records
+                .map(record => record.metrics)
+                .filter(task => task.metadata.type === type);
             const successful = typeTasks.filter(t => t.quality.goalAchieved).length;
             stats.successRate = typeTasks.length > 0 ? successful / typeTasks.length : 0;
         }
+        const channelIds = Array.from(new Set(records.map(record => record.channelId)));
+        for (const channelId of channelIds) {
+            const channelRecords = records.filter(record => record.channelId === channelId);
+            const agentScores = new Map();
+            for (const record of channelRecords) {
+                const scores = agentScores.get(record.agentId) ?? [];
+                scores.push(this.calculateOverallScore(record.metrics));
+                agentScores.set(record.agentId, scores);
+            }
+            analytics.byChannel[channelId] = {
+                totalTasks: channelRecords.length,
+                completedTasks: channelRecords.filter(record => record.metrics.metadata.status === 'completed').length,
+                avgEffectivenessScore: channelRecords.length === 0
+                    ? 0
+                    : channelRecords.reduce((sum, record) => sum + this.calculateOverallScore(record.metrics), 0) / channelRecords.length,
+                topPerformingAgents: Array.from(agentScores.entries())
+                    .sort(([, left], [, right]) => {
+                    const leftAverage = left.reduce((sum, score) => sum + score, 0) / left.length;
+                    const rightAverage = right.reduce((sum, score) => sum + score, 0) / right.length;
+                    return rightAverage - leftAverage;
+                })
+                    .map(([agentId]) => agentId)
+            };
+        }
+        analytics.trends.effectivenessOverTime = records
+            .map(record => ({
+            timestamp: record.metrics.metadata.startTime,
+            avgScore: this.calculateOverallScore(record.metrics),
+            taskCount: 1
+        }))
+            .sort((left, right) => left.timestamp - right.timestamp);
+        if (analytics.trends.effectivenessOverTime.length > 1) {
+            const first = analytics.trends.effectivenessOverTime[0].avgScore;
+            const last = analytics.trends.effectivenessOverTime.at(-1).avgScore;
+            if (last > first) {
+                analytics.trends.improving.push('overall_effectiveness');
+            }
+            else if (last < first) {
+                analytics.trends.declining.push('overall_effectiveness');
+            }
+        }
         // Identify patterns
         analytics.patterns.highPerformanceTasks = Object.entries(analytics.byTaskType)
             .filter(([_, stats]) => stats.successRate > 0.8 && stats.avgAutonomyScore > 0.7)
@@ -415,6 +496,12 @@ export class TaskEffectivenessService {
         analytics.patterns.lowPerformanceTasks = Object.entries(analytics.byTaskType)
             .filter(([_, stats]) => stats.successRate < 0.5 || stats.avgAutonomyScore < 0.3)
             .map(([type]) => type);
+        const teamRecords = records.filter(record => record.metrics.collaboration.participatingAgents.length > 1);
+        analytics.patterns.effectiveTeams = teamRecords.map(record => ({
+            agents: [...record.metrics.collaboration.participatingAgents].sort(),
+            taskTypes: [record.metrics.metadata.type],
+            avgScore: this.calculateOverallScore(record.metrics)
+        }));
         return analytics;
     }
     /**
@@ -425,13 +512,14 @@ export class TaskEffectivenessService {
             case 'step':
                 metrics.performance.stepCount++;
                 break;
-            case 'tool_use':
+            case 'tool_use': {
                 metrics.performance.toolsUsed++;
                 const toolName = event.details.toolName;
                 if (toolName && !metrics.performance.uniqueTools.includes(toolName)) {
                     metrics.performance.uniqueTools.push(toolName);
                 }
                 break;
+            }
             case 'agent_join':
                 if (event.agentId && !metrics.collaboration.participatingAgents.includes(event.agentId)) {
                     metrics.collaboration.participatingAgents.push(event.agentId);
@@ -533,7 +621,7 @@ export class TaskEffectivenessService {
     /**
      * Generate optimization recommendations
      */
-    generateRecommendations(metrics) {
+    generateRecommendations(metrics, taskKey) {
         const recommendations = [];
         if (metrics.performance.humanInterventions > 0) {
             recommendations.push('Enhance agent training for similar tasks to reduce interventions');
@@ -542,7 +630,7 @@ export class TaskEffectivenessService {
             recommendations.push('Consider tool consolidation for efficiency');
         }
         if (metrics.quality.errorCount > 0) {
-            const commonErrors = this.analyzeCommonErrors(metrics.taskId);
+            const commonErrors = this.analyzeCommonErrors(taskKey);
             if (commonErrors.length > 0) {
                 recommendations.push(`Address common errors: ${commonErrors.join(', ')}`);
             }
@@ -552,8 +640,8 @@ export class TaskEffectivenessService {
     /**
      * Analyze common errors for a task
      */
-    analyzeCommonErrors(taskId) {
-        const events = this.taskEvents.get(taskId) || [];
+    analyzeCommonErrors(taskKey) {
+        const events = this.taskEvents.get(taskKey) || [];
         const errors = events.filter(e => e.type === 'error');
         // Group by error type
         const errorTypes = new Map();
@@ -571,57 +659,66 @@ export class TaskEffectivenessService {
      * Setup event listeners
      */
     setupEventListeners() {
-        // Track tool usage
         EventBus.server.on(Events.Mcp.TOOL_CALL, (payload) => {
-            if (payload.taskId) {
+            const taskId = payload.data?.taskId ?? payload.taskId;
+            if (taskId && payload.agentId && payload.channelId) {
+                const taskKey = this.getTaskKey(taskId, payload.agentId, payload.channelId);
+                if (!this.activeTasks.has(taskKey)) {
+                    return;
+                }
                 this.recordEvent({
                     eventId: uuidv4(),
-                    taskId: payload.taskId,
+                    taskId,
                     timestamp: Date.now(),
                     type: 'tool_use',
                     agentId: payload.agentId,
-                    details: { toolName: payload.toolName }
+                    channelId: payload.channelId,
+                    details: { toolName: payload.data?.toolName ?? payload.toolName }
                 });
             }
         });
-        // Track errors
         EventBus.server.on(Events.Mcp.TOOL_ERROR, (payload) => {
-            if (payload.taskId) {
+            const taskId = payload.data?.taskId ?? payload.taskId;
+            if (taskId && payload.agentId && payload.channelId) {
+                const taskKey = this.getTaskKey(taskId, payload.agentId, payload.channelId);
+                if (!this.activeTasks.has(taskKey)) {
+                    return;
+                }
                 this.recordEvent({
                     eventId: uuidv4(),
-                    taskId: payload.taskId,
+                    taskId,
                     timestamp: Date.now(),
                     type: 'error',
                     agentId: payload.agentId,
+                    channelId: payload.channelId,
                     details: {
                         errorType: 'tool_error',
-                        toolName: payload.toolName,
-                        error: payload.error
+                        toolName: payload.data?.toolName ?? payload.toolName,
+                        error: payload.data?.error ?? payload.error
                     }
                 });
             }
         });
-        // Track agent collaboration
         EventBus.server.on(Events.Message.CHANNEL_MESSAGE, (payload) => {
-            if (payload.taskId) {
-                const metrics = this.activeTasks.get(payload.taskId);
+            const taskId = payload.data?.taskId ?? payload.taskId;
+            if (taskId && payload.agentId && payload.channelId) {
+                const metrics = this.activeTasks.get(this.getTaskKey(taskId, payload.agentId, payload.channelId));
                 if (metrics) {
                     metrics.collaboration.messageCount++;
                 }
             }
         });
     }
-    /**
-     * Get task metrics by ID
-     */
-    async getTaskMetrics(taskId) {
-        // A running task lives in memory; a finished one lives in MongoDB.
-        const activeTask = this.activeTasks.get(taskId);
+    /** Get task metrics for one exact tenant task. */
+    async getTaskMetrics(taskId, agentId, channelId) {
+        this.requireTenantIdentity(agentId, channelId);
+        this.requireTaskIdentity(taskId);
+        const activeTask = this.activeTasks.get(this.getTaskKey(taskId, agentId, channelId));
         if (activeTask) {
             return activeTask;
         }
         try {
-            const taskDoc = await TaskEffectivenessModel.findOne({ taskId }).exec();
+            const taskDoc = await TaskEffectivenessModel.findOne({ taskId, agentId, channelId }).exec();
             return taskDoc ? taskDoc.metrics : null;
         }
         catch (error) {
@@ -630,18 +727,29 @@ export class TaskEffectivenessService {
             throw new Error(`Failed to load task ${taskId}: ${message}`);
         }
     }
-    /**
-     * Get effectiveness trends over time
-     */
-    async getEffectivenessTrends(startTime, endTime, intervalMs, channelId) {
+    /** Get effectiveness trends for one exact agent and channel. */
+    async getEffectivenessTrends(startTime, endTime, intervalMs, agentId, channelId) {
+        this.requireTenantIdentity(agentId, channelId);
+        const records = await this.findCompletedTasks({ startTime, endTime, agentId, channelId });
+        return this.computeEffectivenessTrends(records, startTime, endTime, intervalMs);
+    }
+    /** Trend analytics intended only for the admin-authenticated REST surface. */
+    async getAdministrativeEffectivenessTrends(startTime, endTime, intervalMs, channelId) {
+        const records = await this.findCompletedTasks({ startTime, endTime, channelId });
+        return this.computeEffectivenessTrends(records, startTime, endTime, intervalMs);
+    }
+    computeEffectivenessTrends(records, startTime, endTime, intervalMs) {
+        if (!Number.isFinite(intervalMs) || intervalMs <= 0) {
+            throw new Error('A positive trend interval is required');
+        }
         const dataPoints = [];
         const intervals = Math.floor((endTime - startTime) / intervalMs);
-        // One query for the whole window, then bucket in memory.
-        const tasks = await this.findCompletedTasks({ startTime, endTime, channelId });
         for (let i = 0; i < intervals; i++) {
             const intervalStart = startTime + (i * intervalMs);
             const intervalEnd = intervalStart + intervalMs;
-            const intervalTasks = tasks.filter(task => task.metadata.startTime >= intervalStart &&
+            const intervalTasks = records
+                .map(record => record.metrics)
+                .filter(task => task.metadata.startTime >= intervalStart &&
                 task.metadata.startTime < intervalEnd);
             if (intervalTasks.length > 0) {
                 const avgScore = intervalTasks.reduce((sum, task) => sum + this.calculateOverallScore(task), 0) / intervalTasks.length;
@@ -663,12 +771,22 @@ export class TaskEffectivenessService {
             timeRange: { start: startTime, end: endTime }
         };
     }
-    /**
-     * Get agent-specific effectiveness
-     */
+    /** Get agent-specific effectiveness in one exact channel. */
     async getAgentEffectiveness(agentId, startTime, endTime, channelId) {
-        // The agentIds index on the document does the channel/time/agent filtering.
-        const agentTasks = await this.findCompletedTasks({ startTime, endTime, channelId, agentId });
+        this.requireTenantIdentity(agentId, channelId);
+        const records = await this.findCompletedTasks({ startTime, endTime, channelId, agentId });
+        return this.computeAgentEffectiveness(agentId, records, startTime, endTime);
+    }
+    /** Agent analytics intended only for the admin-authenticated REST surface. */
+    async getAdministrativeAgentEffectiveness(agentId, startTime, endTime, channelId) {
+        if (!agentId?.trim()) {
+            throw new Error('Agent ID is required');
+        }
+        const records = await this.findCompletedTasks({ startTime, endTime, channelId, agentId });
+        return this.computeAgentEffectiveness(agentId, records, startTime, endTime);
+    }
+    computeAgentEffectiveness(agentId, records, startTime, endTime) {
+        const agentTasks = records.map(record => record.metrics);
         const totalTasks = agentTasks.length;
         const successfulTasks = agentTasks.filter(t => t.quality.goalAchieved).length;
         const successRate = totalTasks > 0 ? successfulTasks / totalTasks : 0;