@amitdeshmukh/ax-crew 3.11.3 → 4.0.1

package/CHANGELOG.md

@@ -1,4 +1,28 @@
 # Changelog
+## [4.0.1] - 2025-08-24
+
+### Added
+- Dependency: `big.js` for precise accumulation of estimated costs.
+- Dev Dependency: `@types/big.js` for TypeScript support.
+
+### Changed
+- Switched crew cost reporting to metrics-based API. Use `agent.getMetrics()` and `crew.getCrewMetrics()` instead of legacy cost getters.
+- Estimated cost (`estimatedCostUSD`) is now accumulated with Big.js and reported rounded to 5 decimal places.
+- Tests updated to use metrics assertions; added dummy `ANTHROPIC_API_KEY` in test setup to avoid env failures.
+- Test agent signatures updated to new DSL (`query:string -> queryResponse:string`).
+- Aligned with new `@ax-llm/ax` `ai()` and `agent()` factory methods: enforce canonical provider slugs, pass cost tracker via `options.trackers`, and validate `apiURL` when provided.
+- Updated package versions for `@ax-llm/ax` and `@ax-llm/ax-tools`.
+
+### Deprecated
+- Legacy cost APIs (`getLastUsageCost`, `getAccumulatedCosts`, `getAggregatedCosts`) are deprecated in favor of metrics.
+
+### Removed
+- Tests no longer use `getAggregatedCosts`; replaced with metrics assertions.
+
+### Updated
+- README now documents metrics usage and 5-decimal cost rounding, de-emphasizing legacy cost APIs.
+- README Features now includes "Metrics and Cost Tracking"; examples updated to use metrics (`getMetrics`, `getCrewMetrics`).
+
 
 This Changelog format is based on [Keep a Changelog]
 (https://keepachangelog.com/en/1.0.0/), and this project 

package/README.md

@@ -10,6 +10,7 @@ This repo simplifies development of [AxLLM](https://axllm.dev) AI Agents by usin
 - **Task Execution**: Plan and execute tasks using agents in the crew.
 - **Streaming Support**: Stream agent responses in real-time for better user experience and faster feedback.
 - **Model Context Protocol (MCP)**: Support for MCP to allow agents to use MCP servers.
+- **Metrics and Cost Tracking**: Built-in per-agent and per-crew metrics, including token usage and estimated USD costs (5-decimal rounding).
 
 ## Getting Started
 
@@ -92,12 +93,11 @@ if (planner) {
   // Sub-agent usage - when used by another agent (AI is ignored and agent's own config is used)
   const subAgentResponse = await planner.forward(ai, { task: "Plan something" });
   
-  const cost = planner.getUsageCost();
-  
-  if (cost) {
-    console.log(`Total cost: $${cost.totalCost}`);
-    console.log(`Total tokens: ${cost.tokenMetrics.totalTokens}`);
-  }
+  // Metrics (per-agent and per-crew)
+  const agentMetrics = (planner as any).getMetrics?.();
+  const crewMetrics = crew.getCrewMetrics();
+  console.log('Agent metrics:', agentMetrics);
+  console.log('Crew metrics:', crewMetrics);
 }
 ```
 
@@ -514,7 +514,7 @@ For MCP servers that support streamable HTTP communication:
       "mcpEndpoint": "http://localhost:3002/stream",
       "options": {
         "authorization": "Bearer ey.JhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0..-1234567890.1234567890",
-        "headers": { // Custom headers to include with all HTTP requests Note: Content-Type, Accept, and Mcp-Session-Id are managed automatically
+        "headers": { 
           "X-Custom-Header": "custom-value"
         }
       }
@@ -667,76 +667,45 @@ For new streamable HTTP servers, use:
 
 ### Tracking Usage Costs
 
-The package provides precise cost tracking capabilities for monitoring API usage across individual agents and the entire crew. Costs are calculated using high-precision decimal arithmetic to ensure accuracy.
+The package provides metrics for monitoring API usage across individual agents and the entire crew. Estimated costs are accumulated precisely and rounded to 5 decimal places for reporting.
 
 ```javascript
 // After running an agent's forward method
-const response = await Planner.forward({ task: userQuery });
-
-// Get individual agent costs
-const agentCost = Planner.getLastUsageCost();
-console.log(agentCost);
-/* Output example:
-{
-  promptCost: "0.0003637500000",
-  completionCost: "0.0006100000000",
-  totalCost: "0.0009737500000",
-  tokenMetrics: {
-    promptTokens: 291,
-    completionTokens: 122,
-    totalTokens: 413
-  }
-}
-*/
+await Planner.forward({ task: userQuery });
 
-// Get cumulative costs for the agent
-const cumulativeCost = Planner.getAccumulatedCosts();
-console.log(cumulativeCost);
-/* Output example:
+// Per-agent metrics
+const agentMetrics = (Planner as any).getMetrics?.();
+console.log(agentMetrics);
+/* Example:
 {
-  promptCost: "0.0003637500000",
-  completionCost: "0.0006100000000",
-  totalCost: "0.0009737500000",
-  tokenMetrics: {
-    promptTokens: 291,
-    completionTokens: 122,
-    totalTokens: 413
-  }
+  provider: "anthropic",
+  model: "claude-3-haiku-20240307",
+  requests: { totalRequests, totalErrors, errorRate, totalStreamingRequests, durationMsSum, durationCount },
+  tokens: { promptTokens, completionTokens, totalTokens },
+  estimatedCostUSD: 0.00091, // rounded to 5 decimals
+  functions: { totalFunctionCalls, totalFunctionLatencyMs }
 }
 */
 
-// Get aggregated costs for all agents in the crew
-const crewCosts = crew.getAggregatedCosts();
-console.log(crewCosts);
-/* Output example:
+// Crew metrics
+const crewMetrics = crew.getCrewMetrics();
+console.log(crewMetrics);
+/* Example:
 {
-  totalCost: "0.0025482500000",
-  byAgent: {
-    "Planner": { ... },
-    "Calculator": { ... },
-    "Manager": { ... }
-  },
-  aggregatedMetrics: {
-    promptTokens: 850,
-    completionTokens: 324,
-    totalTokens: 1174,
-    promptCost: "0.0010625000000",
-    completionCost: "0.0014857500000"
-  }
+  requests: { ... },
+  tokens: { promptTokens, completionTokens, totalTokens },
+  estimatedCostUSD: 0.00255, // rounded to 5 decimals
+  functions: { ... }
 }
 */
 
-// Reset cost tracking if needed
+// Reset tracked metrics
 crew.resetCosts();
 ```
 
-Cost tracking features:
-- High-precision decimal calculations using decimal.js
-- Per-agent cost breakdown
-- Aggregated crew-wide metrics
-- Token usage statistics
-- Support for different pricing tiers per model
-- Persistent cost tracking across multiple agent runs
+Notes:
+- Legacy cost APIs (`getLastUsageCost`, `getAccumulatedCosts`, `getAggregatedCosts`) are superseded by metrics methods.
+- Estimated cost values are numbers rounded to 5 decimal places.
 
 ## Changelog
 

package/dist/agents/agentConfig.d.ts

@@ -1,10 +1,9 @@
+import { AxDefaultCostTracker } from '@ax-llm/ax';
 import type { AxFunction } from '@ax-llm/ax';
-import type { AgentConfig, CrewConfigInput, FunctionRegistryType, MCPTransportConfig, MCPStdioTransportConfig, MCPHTTPSSETransportConfig, MCPStreambleHTTPTransportConfig } from '../types.js';
-declare const AIConstructors: Record<string, any>;
-export type Provider = keyof typeof AIConstructors;
+import type { AgentConfig, CrewConfigInput, FunctionRegistryType, MCPTransportConfig, MCPStdioTransportConfig, MCPHTTPSSETransportConfig, MCPStreamableHTTPTransportConfig } from '../types.js';
 export declare function isStdioTransport(config: MCPTransportConfig): config is MCPStdioTransportConfig;
 export declare function isHTTPSSETransport(config: MCPTransportConfig): config is MCPHTTPSSETransportConfig;
-export declare function isStreambleHTTPTransport(config: MCPTransportConfig): config is MCPStreambleHTTPTransportConfig;
+export declare function isStreambleHTTPTransport(config: MCPTransportConfig): config is MCPStreamableHTTPTransportConfig;
 /**
  * Parses and returns the AxCrew config from either a JSON config file or a direct JSON object.
  * @param {CrewConfigInput} input - Either a path to the agent config json file or a JSON object with crew configuration.
@@ -27,12 +26,13 @@ declare const parseCrewConfig: (input: CrewConfigInput) => {
  * the API key is not found, or the provider key name is not specified in the configuration.
  */
 declare const parseAgentConfig: (agentName: string, crewConfig: CrewConfigInput, functions: FunctionRegistryType, state: Record<string, any>) => Promise<{
-    ai: any;
+    ai: import("@ax-llm/ax").AxAI<string>;
     name: string;
     description: string;
-    signature: string | import("@ax-llm/ax").AxSignature;
+    signature: string | import("@ax-llm/ax").AxSignature<Record<string, any>, Record<string, any>>;
     functions: AxFunction[];
     subAgentNames: string[];
     examples: Record<string, any>[];
+    tracker: AxDefaultCostTracker;
 }>;
 export { parseAgentConfig, parseCrewConfig };

package/dist/agents/agentConfig.js

@@ -1,26 +1,27 @@
 import fs from 'fs';
-// Import all the providers
-import { AxAIAnthropic, AxAIOpenAI, AxAIAzureOpenAI, AxAICohere, AxAIDeepSeek, AxAIGoogleGemini, AxAIGroq, AxAIHuggingFace, AxAIMistral, AxAIOllama, AxAITogether, AxAIReka, AxAIGrok } from '@ax-llm/ax';
-// Import the MCP client and transports
-import { AxMCPClient, AxMCPHTTPSSETransport, AxMCPStreambleHTTPTransport } from '@ax-llm/ax';
+// Import Ax factory and MCP transports (as exported by current package)
+import { ai, AxMCPClient, AxMCPHTTPSSETransport, AxMCPStreambleHTTPTransport, AxDefaultCostTracker } from '@ax-llm/ax';
+// STDIO transport from tools package
 import { AxMCPStdioTransport } from '@ax-llm/ax-tools';
 import { PROVIDER_API_KEYS } from '../config/index.js';
-// Define a mapping from provider names to their respective constructors
-const AIConstructors = {
-    'anthropic': AxAIAnthropic,
-    'azure-openai': AxAIAzureOpenAI,
-    'cohere': AxAICohere,
-    'deepseek': AxAIDeepSeek,
-    'google-gemini': AxAIGoogleGemini,
-    'groq': AxAIGroq,
-    'huggingFace': AxAIHuggingFace,
-    'mistral': AxAIMistral,
-    'ollama': AxAIOllama,
-    'openai': AxAIOpenAI,
-    'together': AxAITogether,
-    'reka': AxAIReka,
-    'grok': AxAIGrok
-};
+// Canonical provider slugs supported by ai() factory
+const PROVIDER_CANONICAL = new Set([
+    'openai',
+    'anthropic',
+    'google-gemini',
+    'mistral',
+    'groq',
+    'cohere',
+    'together',
+    'deepseek',
+    'ollama',
+    'huggingface',
+    'openrouter',
+    'azure-openai',
+    'reka',
+    'x-grok'
+]);
+// Provider type lives in src/types.ts
 // Type guard to check if config is stdio transport
 export function isStdioTransport(config) {
     return 'command' in config;
@@ -173,11 +174,12 @@ const parseAgentConfig = async (agentName, crewConfig, functions, state) => {
         if (!agentConfigData) {
             throw new Error(`AI agent with name ${agentName} is not configured`);
         }
-        // Get the constructor for the AI agent's provider
-        const AIConstructor = AIConstructors[agentConfigData.provider];
-        if (!AIConstructor) {
-            throw new Error(`AI provider ${agentConfigData.provider} is not supported. Did you mean '${agentConfigData.provider.toLowerCase()}'?`);
+        // Enforce canonical provider slug
+        const lower = agentConfigData.provider.toLowerCase();
+        if (!PROVIDER_CANONICAL.has(lower)) {
+            throw new Error(`AI provider ${agentConfigData.provider} is not supported. Use one of: ${Array.from(PROVIDER_CANONICAL).join(', ')}`);
         }
+        const provider = lower;
         // If an API Key property is present, get the API key for the AI agent from the environment variables
         let apiKey = '';
         if (agentConfigData.providerKeyName) {
@@ -189,26 +191,30 @@ const parseAgentConfig = async (agentName, crewConfig, functions, state) => {
         else {
             throw new Error(`Provider key name is missing in the agent configuration`);
         }
-        // Create an instance of the AI agent and set options
-        const ai = new AIConstructor({
+        // Create a cost tracker instance and pass to ai()
+        const costTracker = new AxDefaultCostTracker();
+        // Create an instance of the AI agent via factory
+        const aiArgs = {
+            name: provider,
             apiKey,
             config: agentConfigData.ai,
             options: {
                 debug: agentConfigData.debug || false,
-                ...agentConfigData.options
+                ...agentConfigData.options,
+                // Attach default cost tracker so usage/costs are recorded by provider layer
+                trackers: [costTracker]
             }
-        });
-        // If an apiURL is provided in the agent config, set it in the AI agent
+        };
         if (agentConfigData.apiURL) {
             try {
-                // Validate apiURL format
                 new URL(agentConfigData.apiURL);
-                ai.setAPIURL(agentConfigData.apiURL);
+                aiArgs.apiURL = agentConfigData.apiURL;
             }
             catch (error) {
                 throw new Error(`Invalid apiURL provided: ${agentConfigData.apiURL}`);
             }
         }
+        const aiInstance = ai(aiArgs);
         // If an mcpServers config is provided in the agent config, convert to functions
         const mcpFunctions = await initializeMCPServers(agentConfigData);
         // Prepare functions for the AI agent
@@ -229,13 +235,14 @@ const parseAgentConfig = async (agentName, crewConfig, functions, state) => {
         ];
         // Return AI instance and Agent parameters
         return {
-            ai,
+            ai: aiInstance,
             name: agentName,
             description: agentConfigData.description,
             signature: agentConfigData.signature,
             functions: agentFunctions,
             subAgentNames: agentConfigData.agents || [],
             examples: agentConfigData.examples || [],
+            tracker: costTracker,
         };
     }
     catch (error) {

package/dist/agents/index.d.ts

@@ -1,11 +1,14 @@
 import { AxAgent, AxAI } from "@ax-llm/ax";
 import type { AxSignature, AxAgentic, AxFunction, AxProgramForwardOptions, AxProgramStreamingForwardOptions, AxGenStreamingOut } from "@ax-llm/ax";
 import type { StateInstance, FunctionRegistryType, UsageCost, CrewConfigInput, MCPTransportConfig } from "../types.js";
-import { StateFulAxAgentUsage } from "./agentUseCosts.js";
 declare class StatefulAxAgent extends AxAgent<any, any> {
     state: StateInstance;
     axai: any;
     private agentName;
+    private costTracker?;
+    private lastRecordedCostUSD;
+    private isAxAIService;
+    private isAxAIInstance;
     constructor(ai: AxAI, options: Readonly<{
         name: string;
         description: string;
@@ -15,12 +18,14 @@ declare class StatefulAxAgent extends AxAgent<any, any> {
         examples?: Array<Record<string, any>> | undefined;
         mcpServers?: Record<string, MCPTransportConfig> | undefined;
     }>, state: StateInstance);
-    forward(values: Record<string, any>, options?: Readonly<AxProgramForwardOptions>): Promise<Record<string, any>>;
-    forward(ai: AxAI, values: Record<string, any>, options?: Readonly<AxProgramForwardOptions>): Promise<Record<string, any>>;
-    streamingForward(values: Record<string, any>, options?: Readonly<AxProgramStreamingForwardOptions>): AxGenStreamingOut<any>;
-    streamingForward(ai: AxAI, values: Record<string, any>, options?: Readonly<AxProgramStreamingForwardOptions>): AxGenStreamingOut<any>;
+    forward(values: Record<string, any>, options?: Readonly<AxProgramForwardOptions<any>>): Promise<Record<string, any>>;
+    forward(ai: AxAI, values: Record<string, any>, options?: Readonly<AxProgramForwardOptions<any>>): Promise<Record<string, any>>;
+    streamingForward(values: Record<string, any>, options?: Readonly<AxProgramStreamingForwardOptions<any>>): AxGenStreamingOut<any>;
+    streamingForward(ai: AxAI, values: Record<string, any>, options?: Readonly<AxProgramStreamingForwardOptions<any>>): AxGenStreamingOut<any>;
     getLastUsageCost(): UsageCost | null;
     getAccumulatedCosts(): UsageCost | null;
+    getMetrics(): import("../metrics/types.js").MetricsSnapshot;
+    resetMetrics(): void;
 }
 /**
  * Represents a crew of agents with shared state functionality.
@@ -63,14 +68,12 @@ declare class AxCrew {
      * Cleans up the crew by dereferencing agents and resetting the state.
      */
     destroy(): void;
-    /**
-     * Gets aggregated costs for all agents in the crew
-     * @returns Aggregated cost information for all agents
-     */
-    getAggregatedCosts(): ReturnType<typeof StateFulAxAgentUsage.getAggregatedCosts>;
     /**
      * Resets all cost tracking for the crew
      */
     resetCosts(): void;
+    getCrewMetrics(): import("../metrics/types.js").MetricsSnapshot;
+    resetCrewMetrics(): void;
 }
 export { AxCrew };
+export type { StatefulAxAgent };

package/dist/agents/index.js

@@ -2,12 +2,20 @@ import { v4 as uuidv4 } from "uuid";
 import { AxAgent } from "@ax-llm/ax";
 import { createState } from "../state/index.js";
 import { parseCrewConfig, parseAgentConfig } from "./agentConfig.js";
-import { StateFulAxAgentUsage } from "./agentUseCosts.js";
+import { MetricsRegistry } from "../metrics/index.js";
 // Extend the AxAgent class from ax-llm
 class StatefulAxAgent extends AxAgent {
     state;
     axai;
     agentName;
+    costTracker;
+    lastRecordedCostUSD = 0;
+    isAxAIService(obj) {
+        return !!obj && typeof obj.getName === 'function' && typeof obj.chat === 'function';
+    }
+    isAxAIInstance(obj) {
+        return !!obj && typeof obj === 'object' && ('defaults' in obj || 'modelInfo' in obj);
+    }
     constructor(ai, options, state) {
         const { examples, ...restOptions } = options;
         const formattedOptions = {
@@ -26,9 +34,12 @@ class StatefulAxAgent extends AxAgent {
     // Implementation
     async forward(first, second, third) {
         let result;
+        const start = performance.now();
+        const crewId = this.state?.crewId || (this.state.get?.('crewId')) || 'default';
+        const labels = { crewId, agent: this.agentName };
         // Track costs regardless of whether it's a direct or sub-agent call
         // This ensures we capture multiple legitimate calls to the same agent
-        if ('apiURL' in first) {
+        if (this.isAxAIService(first)) {
             // Sub-agent case (called with AI service)
             result = await super.forward(this.axai, second, third);
         }
@@ -36,17 +47,51 @@ class StatefulAxAgent extends AxAgent {
             // Direct call case
             result = await super.forward(this.axai, first, second);
         }
-        // Track costs after the call
-        const cost = this.getLastUsageCost();
-        if (cost) {
-            StateFulAxAgentUsage.trackCostInState(this.agentName, cost, this.state);
+        // Track metrics and costs after the call using built-in usage
+        const durationMs = performance.now() - start;
+        MetricsRegistry.recordRequest(labels, false, durationMs);
+        // Always record tokens from built-in usage array if present
+        const builtIn = this.getUsage?.();
+        if (Array.isArray(builtIn)) {
+            const totals = builtIn.reduce((acc, u) => {
+                const pt = u.tokens?.promptTokens ?? u.promptTokens ?? 0;
+                const ct = u.tokens?.completionTokens ?? u.completionTokens ?? 0;
+                acc.promptTokens += typeof pt === 'number' ? pt : 0;
+                acc.completionTokens += typeof ct === 'number' ? ct : 0;
+                // also aggregate per-model to feed Ax tracker
+                const model = u.model || this.axai?.getLastUsedChatModel?.() || this.axai?.defaults?.model;
+                if (model) {
+                    acc.byModel[model] = (acc.byModel[model] || 0) + (pt + ct);
+                }
+                return acc;
+            }, { promptTokens: 0, completionTokens: 0, byModel: {} });
+            MetricsRegistry.recordTokens(labels, {
+                promptTokens: totals.promptTokens,
+                completionTokens: totals.completionTokens,
+                totalTokens: totals.promptTokens + totals.completionTokens,
+            });
+            // Feed Ax's cost tracker with token totals per model; Ax owns pricing
+            const costTracker = this.costTracker;
+            try {
+                for (const [m, count] of Object.entries(totals.byModel)) {
+                    costTracker?.trackTokens?.(count, m);
+                }
+                const totalUSD = Number(costTracker?.getCurrentCost?.() ?? 0);
+                if (!Number.isNaN(totalUSD) && totalUSD > 0) {
+                    MetricsRegistry.recordEstimatedCost(labels, totalUSD);
+                }
+            }
+            catch { }
         }
         return result;
     }
     // Implementation
     streamingForward(first, second, third) {
+        const start = performance.now();
+        const crewId = this.state?.crewId || (this.state.get?.('crewId')) || 'default';
+        const labels = { crewId, agent: this.agentName };
         let streamingResult;
-        if ('apiURL' in first) {
+        if (this.isAxAIService(first)) {
             streamingResult = super.streamingForward(this.axai, second, third);
         }
         else {
@@ -60,34 +105,64 @@ class StatefulAxAgent extends AxAgent {
                 }
             }
             finally {
-                const cost = this.getLastUsageCost();
-                if (cost) {
-                    StateFulAxAgentUsage.trackCostInState(this.agentName, cost, this.state);
+                const durationMs = performance.now() - start;
+                MetricsRegistry.recordRequest(labels, true, durationMs);
+                // Record tokens from built-in usage array if present
+                const builtIn = this.getUsage?.();
+                if (Array.isArray(builtIn)) {
+                    const totals = builtIn.reduce((acc, u) => {
+                        const pt = u.tokens?.promptTokens ?? u.promptTokens ?? 0;
+                        const ct = u.tokens?.completionTokens ?? u.completionTokens ?? 0;
+                        acc.promptTokens += typeof pt === 'number' ? pt : 0;
+                        acc.completionTokens += typeof ct === 'number' ? ct : 0;
+                        const model = u.model || this.axai?.getLastUsedChatModel?.() || this.axai?.defaults?.model;
+                        if (model) {
+                            acc.byModel[model] = (acc.byModel[model] || 0) + (pt + ct);
+                        }
+                        return acc;
+                    }, { promptTokens: 0, completionTokens: 0, byModel: {} });
+                    MetricsRegistry.recordTokens(labels, {
+                        promptTokens: totals.promptTokens,
+                        completionTokens: totals.completionTokens,
+                        totalTokens: totals.promptTokens + totals.completionTokens,
+                    });
+                    const costTracker = this.costTracker;
+                    try {
+                        for (const [m, count] of Object.entries(totals.byModel)) {
+                            costTracker?.trackTokens?.(count, m);
+                        }
+                        const totalUSD = Number(costTracker?.getCurrentCost?.() ?? 0);
+                        if (!Number.isNaN(totalUSD) && totalUSD > 0) {
+                            MetricsRegistry.recordEstimatedCost(labels, totalUSD);
+                        }
+                    }
+                    catch { }
+                }
+                // Record estimated cost (USD) via attached tracker if available
+                const costTracker = this.costTracker;
+                try {
+                    const totalUSD = Number(costTracker?.getCurrentCost?.() ?? 0);
+                    if (!Number.isNaN(totalUSD) && totalUSD > 0) {
+                        MetricsRegistry.recordEstimatedCost(labels, totalUSD);
+                    }
                 }
+                catch { }
             }
         }).bind(this)();
         return wrappedGenerator;
     }
-    // Get the usage cost for the most recent run of the agent
-    getLastUsageCost() {
-        const { modelUsage, modelInfo, defaults } = this.axai;
-        // Check if all required properties exist
-        if (!modelUsage?.promptTokens || !modelUsage?.completionTokens) {
-            return null;
-        }
-        if (!modelInfo || !defaults?.model) {
-            return null;
-        }
-        const currentModelInfo = modelInfo.find((m) => m.name === defaults.model);
-        if (!currentModelInfo?.promptTokenCostPer1M || !currentModelInfo?.completionTokenCostPer1M) {
-            return null;
-        }
-        return StateFulAxAgentUsage.calculateCost(modelUsage, currentModelInfo);
-    }
+    // Legacy cost API removed: rely on Ax trackers for cost reporting
+    getLastUsageCost() { return null; }
     // Get the accumulated costs for all runs of this agent
-    getAccumulatedCosts() {
-        const stateKey = `${StateFulAxAgentUsage.STATE_KEY_PREFIX}${this.agentName}`;
-        return this.state.get(stateKey);
+    getAccumulatedCosts() { return null; }
+    // Metrics API for this agent
+    getMetrics() {
+        const crewId = this.state?.crewId || (this.state.get?.('crewId')) || 'default';
+        return MetricsRegistry.snapshot({ crewId, agent: this.agentName });
+    }
+    resetMetrics() {
+        const crewId = this.state?.crewId || (this.state.get?.('crewId')) || 'default';
+        MetricsRegistry.reset({ crewId, agent: this.agentName });
     }
 }
 /**
@@ -121,6 +196,8 @@ class AxCrew {
         this.crewId = crewId;
         this.agents = new Map();
         this.state = createState(crewId);
+        // Make crewId discoverable to metrics
+        this.state.set('crewId', crewId);
     }
     /**
      * Factory function for creating an agent.
@@ -132,7 +209,7 @@ class AxCrew {
         try {
             const agentConfig = await parseAgentConfig(agentName, this.crewConfig, this.functionsRegistry, this.state);
             // Destructure with type assertion
-            const { ai, name, description, signature, functions, subAgentNames, examples } = agentConfig;
+            const { ai, name, description, signature, functions, subAgentNames, examples, tracker } = agentConfig;
             // Get subagents for the AI agent
             const subAgents = subAgentNames.map((subAgentName) => {
                 if (!this.agents?.get(subAgentName)) {
@@ -140,15 +217,39 @@ class AxCrew {
                 }
                 return this.agents?.get(subAgentName);
             });
+            // Dedupe sub-agents by name (defensive)
+            const subAgentSet = new Map();
+            for (const sa of subAgents.filter((agent) => agent !== undefined)) {
+                const n = sa?.agentName ?? sa?.name ?? '';
+                if (!subAgentSet.has(n))
+                    subAgentSet.set(n, sa);
+            }
+            const uniqueSubAgents = Array.from(subAgentSet.values());
+            // Dedupe functions by name and avoid collision with sub-agent names
+            const subAgentNameSet = new Set(uniqueSubAgents.map((sa) => sa?.agentName ?? sa?.name).filter(Boolean));
+            const uniqueFunctions = [];
+            const seenFn = new Set();
+            for (const fn of functions.filter((fn) => fn !== undefined)) {
+                const fnName = fn.name;
+                if (subAgentNameSet.has(fnName)) {
+                    // Skip function that collides with a sub-agent name
+                    continue;
+                }
+                if (!seenFn.has(fnName)) {
+                    seenFn.add(fnName);
+                    uniqueFunctions.push(fn);
+                }
+            }
             // Create an instance of StatefulAxAgent
             const agent = new StatefulAxAgent(ai, {
                 name,
                 description,
                 signature,
-                functions: functions.filter((fn) => fn !== undefined),
-                agents: subAgents.filter((agent) => agent !== undefined),
+                functions: uniqueFunctions,
+                agents: uniqueSubAgents,
                 examples,
             }, this.state);
+            agent.costTracker = tracker;
             return agent;
         }
         catch (error) {
@@ -273,18 +374,31 @@ class AxCrew {
         this.agents = null;
         this.state.reset();
     }
-    /**
-     * Gets aggregated costs for all agents in the crew
-     * @returns Aggregated cost information for all agents
-     */
-    getAggregatedCosts() {
-        return StateFulAxAgentUsage.getAggregatedCosts(this.state);
-    }
     /**
      * Resets all cost tracking for the crew
      */
     resetCosts() {
-        StateFulAxAgentUsage.resetCosts(this.state);
+        // Reset AxAgent built-in usage and our metrics registry
+        if (this.agents) {
+            for (const [, agent] of this.agents) {
+                try {
+                    agent.resetUsage?.();
+                }
+                catch { }
+                try {
+                    agent.resetMetrics?.();
+                }
+                catch { }
+            }
+        }
+        MetricsRegistry.reset({ crewId: this.crewId });
+    }
+    // Metrics API
+    getCrewMetrics() {
+        return MetricsRegistry.snapshotCrew(this.crewId);
+    }
+    resetCrewMetrics() {
+        MetricsRegistry.reset({ crewId: this.crewId });
     }
 }
 export { AxCrew };

package/dist/index.d.ts

@@ -2,6 +2,8 @@ import { AxCrew } from './agents/index.js';
 import { AxCrewFunctions } from './functions/index.js';
 import type { CrewConfigInput, AgentConfig } from './types.js';
 import type { UsageCost, AggregatedMetrics, AggregatedCosts, StateInstance, FunctionRegistryType } from './types.js';
+export * from './metrics/index.js';
+export { MetricsRegistry } from './metrics/index.js';
 /**
  * The configuration for an AxCrew.
  *

package/dist/index.js

@@ -1,3 +1,5 @@
 import { AxCrew } from './agents/index.js';
 import { AxCrewFunctions } from './functions/index.js';
+export * from './metrics/index.js';
+export { MetricsRegistry } from './metrics/index.js';
 export { AxCrew, AxCrewFunctions, };